SuperAPI AI 工具集

api-doc-gen

编程与开发

查看项目

更新于 11-06 16:18

技能介绍

用途

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”,资料未说明更细粒度的响应内容推断