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:框架特定示例