name: api-documentation-generator description: 从API路由文件生成OpenAPI/Swagger文档。在处理REST API、Express路由、FastAPI端点或用户请求API文档时使用。 allowed-tools: Read, Grep, Glob, Write, Edit
API文档生成器
此技能可从代码库中的API路由文件自动生成OpenAPI 3.0（Swagger）文档。
何时使用此技能
- 用户要求生成API文档时
- 处理REST API端点时
- 需要创建或更新OpenAPI/Swagger规范时
- 为Express、FastAPI、Flask、NestJS或类似框架设置API文档时
使用说明
1. 发现API路由
搜索代码库中的API路由定义：
- Express/Node.js：查找
app.get()、app.post()、router.get()等 - FastAPI/Python：查找
@app.get()、@router.post()装饰器 - Flask：查找
@app.route()装饰器 - NestJS：查找
@Get()、@Post()、@Controller()装饰器 - Rails：在
config/routes.rb中查找路由
使用Glob查找路由文件（例如：**/*routes*.{js,ts,py}、**/controllers/**/*.{js,ts}）
2. 分析路由模式
对每个发现的路由，提取：
- HTTP方法：GET、POST、PUT、PATCH、DELETE
- 路径：端点URL（例如：
/api/users/:id） - 参数：路径参数、查询参数、请求体
- 响应：预期的响应结构
- 认证：是否需要认证
- 描述：路由附近的注释或文档字符串
3. 生成OpenAPI规范
创建或更新OpenAPI 3.0规范文件（通常是openapi.yaml或swagger.json）：
- 从
templates/openapi-3.0.yaml中的模板开始 - 将每个路由映射到OpenAPI路径对象
- 使用JSON Schema定义请求/响应模式
- 包含参数定义（路径、查询、请求体）
- 如果检测到认证方案则添加（Bearer、API Key、OAuth2）
- 按标签对端点进行分组（例如：“用户”、“产品”、“认证”）
4. 验证完整性
检查生成的文档是否包含：
- 所有发现的端点
- 准确的HTTP方法和路径
- 可能的请求/响应示例
- 错误响应（400、401、404、500等）
- 安全要求
5. 输出位置
- 保存为项目根目录中的
openapi.yaml，或 - 如果存在
docs/或api/目录，则放置在其中 - 如果不明确，询问用户首选位置
框架特定说明
Express/Node.js
- 检查可能影响认证/验证的路由中间件
- 查找请求验证器（Joi、express-validator等）
- 提取端点描述的JSDoc注释
FastAPI
- FastAPI自动生成OpenAPI文档，但此技能可以增强它们
- 提取请求/响应模式的Pydantic模型
- 检查
response_model和status_code参数
NestJS
- 查找模式的DTO（数据传输对象）
- 检查Swagger装饰器（
@ApiOperation、@ApiResponse） - 从控制器和方法装饰器中提取元数据
最佳实践
- 使用现有模式：如果代码库有TypeScript接口、Pydantic模型或类似内容，请使用它们以获得准确的模式
- 包含示例：如果可用，从测试中添加请求/响应示例
- 逻辑分组：使用标签按资源或功能区域组织端点
- 适当版本控制：使用代码库中的API版本（例如：“1.0.0”）
- 添加描述：使用代码注释/文档字符串作为端点描述
支持文件
templates/openapi-3.0.yaml：基础OpenAPI模板examples.md：框架特定示例