API文档自动生成Skill:扫一遍源码,直接产出标准 OpenAPI 文档
- 它是什么:api-doc-gen 是一个从源代码路由定义中自动扫描并生成 OpenAPI 3.0.3 规范文档的 AI 技能,技能 ID 为 14277。
- 支持哪些框架:Flask、FastAPI、Django REST Framework、Express.js、Gin、Echo,可自动检测框架类型。
- 能提取什么:HTTP 方法、路由路径、路径参数、查询参数、请求体、响应模型、接口描述与标签分组。
- 怎么用:通过一条
python scripts/generate_api_doc.py ./src命令或直接向 AI 助手描述需求即可触发,输出 JSON / YAML,可直接导入 Swagger UI 或 Redoc。 - 门槛极低:只需 Python 3.8+,不依赖任何第三方库,全部基于标准库实现,MIT 协议开源。
该技能叫什么?如何下载安装 AI 技能提升开发效率?
技能中文名:API文档自动生成Skill 技能英文名:api-doc-gen 技能 ID:14277
它要解决的问题非常具体:接口文档往往由人工编写,或者只在需求文档里写一份草稿,代码一旦迭代,文档就过期;而当团队里同时存在 Flask、FastAPI、Express、Gin 等多种技术栈时,各家路径参数写法还不统一(<int:user_id>、{user_id}、:user_id),手工整理成 OpenAPI 规范耗时且容易出错。api-doc-gen 的思路是把这件事交给源码本身——路由定义在哪里,文档就从哪里长出来。
一键安装 AI 技能提升开发效率的思路与步骤:
- 确认安装前提:本机需要 Python 3.8 及以上版本;被扫描的项目必须是详情中列出的受支持框架(Flask、FastAPI、Django REST Framework、Express.js、Gin、Echo)。技能本身无需安装任何额外依赖,仅使用 Python 标准库。
- 在技能市场安装技能:在所用 AI 技能平台的技能市场或技能库中,按技能名称「API文档自动生成Skill」、英文名
api-doc-gen或技能 ID14277检索,进入详情页点击安装 / 启用即可。具体入口路径与账号要求以官方说明为准。 - 在会话中启用:安装完成后,在 AI 助手/Agent 的工具或技能列表中确认该技能处于启用状态,后续对话中提到「生成 API 文档」「OpenAPI」「Swagger」「接口文档」「路由扫描」等关键词时即可触发。
- 验证是否生效:让它扫描一个已知的小项目目录,例如提示「用 api-doc-gen 扫描 ./src 生成 OpenAPI 文档」,若能返回以
"openapi": "3.0.3"开头的 JSON 结构(或 YAML),说明技能已正常工作;也可以在本地直接执行python scripts/generate_api_doc.py ./src验证脚本可用性。 - 接入文档平台:把生成的
api-spec.yaml或 JSON 文件导入 Swagger UI / Redoc,即可获得可交互的在线接口文档。
该技能的主要功能和特点
- 自动检测框架类型:无需手工声明,扫描时自动识别源码属于哪个框架;也可用
--framework参数强制指定,避免混合仓库误判。 - 多框架、多语言覆盖:Python 侧支持 Flask、FastAPI、Django REST Framework(AST 解析,结合装饰器、类型注解、docstring 与 Pydantic 模型);JavaScript/TypeScript 侧支持 Express.js(正则匹配
app.get()/router.get()并结合 JSDoc);Go 侧支持 Gin 与 Echo(正则匹配路由调用与注释)。 - 信息提取维度完整:HTTP 方法、路由路径、路径参数(含类型推断)、查询参数(Python 框架从函数签名提取)、请求体(FastAPI 从类型注解与 Pydantic 模型推断)、响应模型(FastAPI 从
response_model提取)、接口描述(docstring / JSDoc / 行注释)、标签分组(按源文件模块名自动归类)。 - 路径参数格式统一:自动把各框架的路径参数写法转换为 OpenAPI 的
{param}格式,Flask 的<int:user_id>还会带上整数类型,Express / Gin / Echo 的:user_id统一转为{user_id}。 - 输出即用:输出严格符合 OpenAPI 3.0.3 规范,支持
json与yaml两种格式,可直接被 Swagger UI、Redoc 等主流工具消费。 - 零依赖、可脚本化:仅用 Python 标准库实现,适合放进 CI 流水线或本地 Git Hook,随时重新生成。
和普通做法相比,它强在「不用另建一份文档源」:接口描述的来源就是代码里的装饰器、类型注解和注释,文档天然跟着代码走。
如何使用该技能?
第 1 步:明确扫描目标
确定要扫描的源码目录,例如 ./src、./app 或 ./routes。目录越聚焦,生成的文档越干净。
第 2 步:用自然语言触发技能 在 AI 助手中直接描述需求即可,例如:「扫描 ./app 目录里的 FastAPI 代码,生成 OpenAPI 3.0 文档,标题叫订单服务 API,版本 2.0.0,格式用 YAML。」技能会按描述转换成对应参数执行。
第 3 步:或使用命令行精确控制 详情中给出的典型调用方式:
# 扫描源码目录,输出 JSON 格式 OpenAPI 规范
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
第 4 步:按需调整参数
source_dir(必填,源码目录);-f/--format(json 或 yaml,默认 json);-o/--output(输出文件路径,默认输出到 stdout);--framework(强制指定框架,默认自动检测);--title(默认 API Documentation);--version(默认 1.0.0);--description(默认空);--server(服务器地址,可多次指定)。
第 5 步:读取输出
不指定 --output 时结果打印到标准输出,形如:"openapi": "3.0.3",info 下含 title、version,paths 下按路径和方法组织,每个操作包含 summary、operationId、tags、parameters、responses。例如 /users/{user_id} 的 GET 会生成 operationId: get_user、tags: ["users"],并把 user_id 标记为 in: path、required: true、类型为整数。
第 6 步:导入文档平台校验 把输出文件导入 Swagger UI / Redoc,检查接口数量、参数类型、描述文字是否与预期一致,补齐注释后重新生成即可。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| api-doc-gen(本技能) | 多框架源码扫描生成 OpenAPI | 扫描 Flask/FastAPI/DRF/Express/Gin/Echo 路由,提取参数、请求体、响应模型、注释,输出 JSON/YAML | 需 Python 3.8+,无第三方依赖,一条命令或一句话触发 | 多技术栈混用、存量项目补文档、CI 定期生成 | 优势:跨语言跨框架统一产出、零依赖、上手快;不足:Go/Express 采用正则匹配,注释写得不规范时描述信息会缺失 |
| 框架自带文档能力(如 FastAPI 的 OpenAPI 输出) | 框架内建 | 运行时直接暴露 OpenAPI 规范 | 无需额外操作 | 纯 FastAPI 单体项目 | 优势:零成本、永远与运行时一致;不足:只覆盖本框架,无法处理 Flask/Express/Gin,也无法离线扫描未运行的项目 |
| 手写 OpenAPI / Swagger 规范文件 | 人工维护 | 完全自由地描述接口 | 需熟悉 OpenAPI 规范,人力成本高 | 接口少且稳定的项目 | 优势:可控性最强;不足:极易与代码脱节,接口一多维护成本急剧上升 |
| 调试工具导出的接口集合 | 抓包 / 手工调试沉淀 | 从请求记录生成接口描述 | 需逐个接口手工调用 | 第三方接口逆向、少量接口 | 优势:无需读源码;不足:只能覆盖被调用过的接口,参数类型与响应模型难以准确推导 |
该技能的典型应用场景与实际体验情况
场景一:接手存量项目的后端新人
入职后拿到一个写了三年的 Flask 项目,没有任何接口文档,交接只能靠问人。用 api-doc-gen 扫描 ./src,一次得到全部路由清单和路径参数类型,再导入 Swagger UI,半天内就能对项目接口形成整体认知。
场景二:前后端联调前的文档交付
前端等待接口定义,后端嫌写文档麻烦。约定好 docstring / JSDoc 写法后,后端改完代码直接重新生成一份 api-spec.yaml 给前端,接口变更当天同步。
场景三:多语言微服务的文档归一
网关侧使用 Go(Gin),业务侧使用 Python(FastAPI),管理后台接口使用 Node(Express)。三种写法各不相同,本技能会自动把 :user_id、<int:user_id>、{user_id} 统一成 {user_id},输出同一套 OpenAPI 规范,方便汇总到一个文档门户。
场景四:CI 中的文档漂移检测 在流水线里定时执行生成命令,把本次输出与仓库中的旧规范文件对比,一旦出现未登记的接口变更就提示补充说明,让文档不再"过期"。
实际体验情况:
- 上手难度:低。前置条件只有 Python 3.8+,不用配环境、不用装包,一条命令或一句话就能跑。
- 效果:Python 框架走 AST 解析,参数类型、请求体、响应模型都能推得比较准;自动分组标签和自动生成的
operationId让文档结构清晰。 - 注意事项:Express、Gin、Echo 采用正则匹配,路由写法和注释规范程度会直接影响提取完整度,建议保持
router.get(...)这类标准写法并补齐注释;响应模型目前主要从 FastAPI 的response_model提取,其他框架的响应结构建议人工补充;生成后仍建议在 Swagger UI 里过一遍,确认必填项与类型。
该技能能为用户带来的价值
- 把文档成本从"小时级"压到"分钟级":原本需要逐个接口翻代码、抄路径、对参数,现在一次扫描即可拿到完整骨架,人力集中在补充业务描述上。
- 消除文档与代码的脱节:文档源就是代码本身,接口改动后重新生成即可,避免"文档写的是三个月前的接口"这类事故。
- 降低跨栈协作门槛:不同语言、不同框架的路径参数写法被统一成 OpenAPI 标准格式,团队不需要为每个技术栈单独准备一套文档工具。
- 零成本接入现有工具链:输出标准 OpenAPI 3.0.3,可直接喂给 Swagger UI、Redoc、接口测试与 SDK 生成工具,无需额外转换。
- 长期价值:配合 CI 使用后,接口文档从"一次性交付物"变成"可持续校验的产物",为接口评审、契约测试和对外 API 开放打下基础。
常见问题 FAQ
Q1:这个技能怎么安装?
在所用 AI 技能平台的技能库中按名称「API文档自动生成Skill」、英文名 api-doc-gen 或技能 ID 14277 搜索并安装启用即可;本地运行只需 Python 3.8+,不需要 pip 安装任何第三方依赖。具体安装入口以官方说明为准。
Q2:使用它收费吗? 技能本身以 MIT 协议开源,不涉及额外依赖与授权成本;平台侧是否收费、如何计费以官方说明为准。
Q3:支持哪些框架?我的项目是 Django 普通视图可以吗?
详情中明确支持 Python 的 Flask、FastAPI、Django REST Framework(@api_view 装饰器),JavaScript/TypeScript 的 Express.js,Go 的 Gin 与 Echo。Django 普通函数视图或类视图不在支持列表内,建议先确认是否使用 DRF。
Q4:生成出来的接口描述是空的怎么办?
接口的 summary 来自 docstring、JSDoc 或行注释。若描述缺失,先给对应函数补上注释再重新生成;Express、Gin、Echo 走正则匹配,请检查路由是否使用了 app.get() / router.get() / r.GET() / group.GET() 等标准写法。
Q5:它和 Swagger UI 是什么关系?需要二选一吗? 不是替代关系。api-doc-gen 负责生产 OpenAPI 3.0.3 规范文件,Swagger UI / Redoc 负责把该文件渲染成可交互的在线文档,两者配合使用效果最好。