api-doc-generator
从源代码生成 OpenAPI 3.0 文档
手动编写 API 文档速度慢，而且往往不完整。此技能会直接从你的代码自动生成 OpenAPI 3.0 规范、请求示例和 Postman collections，让你的团队始终拥有准确的 API 文档。
下载技能 ZIP
在 Claude 中上传
前往 设置 → 功能 → 技能 → 上传技能
开启并开始使用
Agent 可读资源
当 AI Agent、爬虫或脚本需要干净上下文、而不是读取完整页面时，请使用这些链接。
测试它
正在使用“api-doc-generator”。 Express route: GET /users/:id 返回 { id, name, email }，status 为 200 或 404
预期结果:
OpenAPI 3.0 YAML，记录 GET /users/{id}，包含 path parameter schema、成功响应 schema（包括 id (integer)、name (string)、email (string)）以及 404 错误响应定义
正在使用“api-doc-generator”。 POST /orders endpoint 接收 { productId, quantity, shippingAddress } 并返回 { orderId, status, total }
预期结果:
完整的 request body schema，包含 required fields、带订单确认详情的 response schema，以及带示例 JSON payload、可直接使用的 Postman collection entry
正在使用“api-doc-generator”。 将这份内部 API 文档重构为面向公众的 OpenAPI reference
预期结果:
整理后的 OpenAPI specification，包含 security scheme definitions、速率限制文档、versioning headers，以及适合公共开发者门户的 Markdown 格式 endpoint 描述
安全审计
安全Two static analysis findings evaluated and dismissed as false positives. The 'weak cryptographic algorithm' alert on SKILL.md:4 is a YAML description field with no cryptography. The 'high file entropy' alert is caused by CJK/Chinese UTF-8 characters, which naturally have higher entropy than ASCII text. No actual security threats found: no network access, no filesystem operations, no external commands, no scripts, no environment variable access, and no prompt injection attempts detected.
检测到的模式
质量评分
你能构建什么
从后端代码自动生成 API 文档
后端开发者粘贴 route handlers 或 controller files，即可获得完整的 OpenAPI 3.0 规范文档，可直接供团队使用。
为入门引导创建 Postman Collections
前端开发者和新团队成员可获得带有示例请求、可直接导入的 Postman collections，从而立即探索和测试 API。
统一团队间的 API 文档标准
工程负责人使用此技能在各个微服务中强制执行一致的 OpenAPI 文档，确保每个 API 都遵循相同的规范格式。
试试这些提示
为这个 Express route handler 生成 API 文档。包括 HTTP method、path、request parameters 和 response format。
为这个 REST API controller 创建完整的 OpenAPI 3.0 YAML specification。包括所有 endpoints、request schemas、response schemas 和 error codes。
根据这个 API definition 生成 Postman collection JSON。包括 authorization headers、示例 request bodies，以及每个 endpoint 的 test scripts。
从这些使用 Python、Java 和 TypeScript 编写的 source files 中提取 API definitions。生成一个命名和示例一致的统一 OpenAPI 3.0 specification。
最佳实践
- 提供包含所有 routes 和 handlers 的完整源代码文件，以获得最全面的文档输出
- 始终审查生成的 OpenAPI specs 是否正确，并补充代码本身无法表达的业务逻辑细节
- 在 prompt 中包含示例 request payloads 和预期 response data，以生成更丰富的 API 文档
避免
- 请求生成文档时，不要粘贴包含 API keys、tokens 或 secrets 的源代码
- 在发布生成的 API 文档之前，不要跳过对 endpoint 描述和 schemas 的审查与修正
- 避免记录不应暴露给外部 API consumers 的内部专用或已弃用 endpoints