route-to-openapi

route-to-openapi

自动扫描源代码中的路由/端点定义，生成符合 OpenAPI 3.0.3 规范的 RESTful API 文档。

支持主流 Web 框架，并可自动检测框架。提取 HTTP 方法、路径、参数、请求正文、响应模型和文档注释，然后输出标准 OpenAPI 规范文件，可直接导入 Swagger UI 或 Redoc。

快速开始

# Scan source directory, output OpenAPI spec in JSON format
python scripts/generate_api_doc.py ./src

# Specify output format and file
python scripts/generate_api_doc.py ./src --format yaml --output api-spec.yaml

# Specify framework and API metadata
python scripts/generate_api_doc.py ./app --framework flask --title "My API" --version 2.0.0

# Add server URLs
python scripts/generate_api_doc.py ./routes --server http://localhost:3000 --server https://api.example.com

支持的框架

语言	框架	解析方式
Python	Flask	AST 解析（装饰器 + 类型注解 + 文档字符串）
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）
• 端点描述：从文档字符串 / JSDoc / 行内注释中提取
• 标签分组：按源文件模块名称自动分组

路径参数格式转换

框架	源格式	转换结果
Flask	<int:user_id>	{user_id}（类型：整数）
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	输出文件路径	标准输出
--framework	指定框架（跳过自动检测）	自动检测
--title	API 文档标题	API Documentation
--version	API 版本号	1.0.0
--description	API 描述文本	空
--server	服务 URL（可多次指定）	无

输出示例

{
  "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" }
        }
      }
    }
  }
}

前置条件

• Python 3.8+
• 无需额外依赖 — 仅使用 Python 标准库
• 扫描的项目必须使用上述支持的 Web 框架之一