用途
api-doc-gen 用于从现有源代码的路由与端点定义中自动扫描并生成符合 OpenAPI 3.0.3 规范的 RESTful API 文档。它适合已有 Web 项目、希望减少手工编写接口文档工作的场景。
主要能力
工具自动检测被扫描项目所用的 Web 框架,并从代码中提取以下信息:
- HTTP 方法:GET、POST、PUT、DELETE、PATCH 等
- 路由路径:将各框架的路径参数格式统一转换为 OpenAPI 的 {param} 格式
- 路径参数:从路由模式中提取并做类型推断
- 查询参数:从 Python 框架的函数签名中提取
- 请求体:从类型注解和 Pydantic 模型中推断(FastAPI)
- 响应模型:从 response_model 参数中提取(FastAPI)
- 接口描述:从 docstring、JSDoc 或行注释中提取
- 标签分组:按源文件模块名自动分组
输出格式为 JSON 或 YAML,可直接导入 Swagger UI 或 Redoc。
支持的框架
| 语言 | 框架 | 解析方式 |
|---|---|---|
| Python | Flask | AST 解析(装饰器 + 类型注解 + docstring) |
| Python | FastAPI | AST 解析(装饰器 + Pydantic 模型 + 类型注解) |
| Python | Django REST Framework | AST 解析(@api_view 装饰器) |
| JavaScript/TypeScript | Express.js | 正则匹配(app.get() / router.get() + JSDoc) |
| Go | Gin | 正则匹配(r.GET() / group.GET() + 注释) |
| Go | Echo | 正则匹配(e.GET() + 注释) |
使用方式
前置条件:Python 3.8+,无需安装额外依赖,仅使用 Python 标准库;被扫描的项目需使用上表所列的 Web 框架。
快速开始:
# 扫描源码目录,输出 JSON 格式 OpenAPI spec
python scripts/generate_api_doc.py ./src
# 指定输出格式和文件
python scripts/generate_api_doc.py ./src --format yaml --output api-spec.yaml
# 指定框架和 API 元信息
python scripts/generate_api_doc.py ./app --framework flask --title "My API" --version 2.0.0
# 添加服务器地址
python scripts/generate_api_doc.py ./routes --server http://localhost:3000 --server https://api.example.com
参数说明:
| 参数 | 说明 | 默认值 |
|---|---|---|
| source_dir | 要扫描的源码目录(必填) | - |
| -f, --format | 输出格式:json 或 yaml | json |
| -o, --output | 输出文件路径 | stdout |
| --framework | 强制指定框架(不自动检测) | 自动检测 |
| --title | API 文档标题 | API Documentation |
| --version | API 版本号 | 1.0.0 |
| --description | API 描述文字 | 空 |
| --server | 服务器地址(可多次指定) | 无 |
路径参数格式转换
| 框架 | 源格式 | 转换结果 |
|---|---|---|
| Flask | int:user_id | {user_id} (type: integer) |
| FastAPI | {user_id} | {user_id} (保持不变) |
| Express | :user_id | {user_id} |
| Gin/Echo | :user_id | {user_id} |
适用场景
- 已有 Flask、FastAPI、DRF、Express、Gin、Echo 项目,需要批量生成 OpenAPI 规范文件
- 需要将生成的规范直接导入 Swagger UI 或 Redoc 进行展示
- 希望通过代码注释与类型注解维护接口文档,减少手工编写
限制
- 仅支持上表列出的框架;被扫描项目需使用这些框架
- 各框架的提取能力不同:查询参数主要来自 Python 框架函数签名,请求体与响应模型主要来自 FastAPI 的 Pydantic 模型与 response_model,其他框架的对应信息提取能力资料未详细说明
- Express、Gin、Echo 采用正则匹配解析,Flask、FastAPI、DRF 采用 AST 解析
- 生成的响应默认描述为 “Successful response”,资料未说明更细粒度的响应内容推断