Automatically scan route/endpoint definitions from source code and generate documentation compliant with the OpenAPI 3.0.3 specification for RESTful APIs.
Supports mainstream web frameworks, automatically detects the framework type, extracts HTTP methods, paths, parameters, request bodies, response models, and documentation comments, and outputs a standard OpenAPI specification file that can be directly imported into Swagger UI / Redoc.
Quick Start
# 扫描源码目录,输出 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
Add server address
python scripts/generate_api_doc.py ./routes --server http://localhost:3000 --server https://api.example.com
## 支持的框架
| 语言 | 框架 | 解析方式 |
|---|---|---|
| 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()` + 注释) |
## 提取能力
脚本会自动提取以下信息:
- **HTTP 方法**:GET / POST / PUT / DELETE / PATCH 等
- **路由路径**:自动转换各框架路径参数格式为 OpenAPI `{param}` 格式
- **路径参数**:从路由模式中提取(含类型推断)
- **查询参数**:从函数签名中提取(Python 框架)
- **请求体**:从类型注解和 Pydantic 模型中推断(FastAPI)
- **响应模型**:从 `response_model` 参数中提取(FastAPI)
- **接口描述**:从 docstring / JSDoc / 行注释中提取
- **标签分组**:按源文件模块名自动分组
## 路径参数格式转换
| 框架 | 源格式 | 转换结果 |
|---|---|---|
| Flask | `<int:user_id>` | `{user_id}` (type: integer) |
| FastAPI | `{user_id}` | `{user_id}` (保持不变) |
| Express | `:user_id` | `{user_id}` |
| Gin/Echo | `:user_id` | `{user_id}` |
## 参数说明
| 参数 | 说明 | 默认值 |
|---|---|---|
| `source_dir` | 要扫描的源码目录(必填) | - |
| `-f, --format` | 输出格式:`json` 或 `yaml` | `json` |
| `-o, --output` | 输出文件路径 | stdout |
| `--framework` | 强制指定框架(不自动检测) | 自动检测 |
| `--title` | API 文档标题 | `API Documentation` |
| `--version` | API 版本号 | `1.0.0` |
| `--description` | API 描述文字 | 空 |
| `--server` | 服务器地址(可多次指定) | 无 |
## 输出示例
```json
{
"openapi": "3.0.3",
"info": {
"title": "My API",
"version": "1.0.0"
},
"paths": {
"/users": {
"get": {
"summary": "List all users",
"operationId": "list_users",
"tags": ["users"],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": { "type": "integer" }
}
],
"responses": {
"200": { "description": "Successful response" }
}
}
},
"/users/{user_id}": {
"get": {
"summary": "Get user by ID",
"operationId": "get_user",
"tags": ["users"],
"parameters": [
{
"name": "user_id",
"in": "path",
"required": true,
"schema": { "type": "integer" }
}
],
"responses": {
"200": { "description": "Successful response" }
}
}
}
}
}
Prerequisites
- Python 3.8+
- No additional dependencies need to be installed; only the Python standard library is used
- The project being scanned must use one of the supported web frameworks listed above