技能使用指南

API文档自动生成Skill 用法详解

API文档自动生成Skillapi-doc-gen
8 个章节 约 14 分钟阅读 AI 智能生成

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 技能提升开发效率的思路与步骤:

  1. 确认安装前提:本机需要 Python 3.8 及以上版本;被扫描的项目必须是详情中列出的受支持框架(Flask、FastAPI、Django REST Framework、Express.js、Gin、Echo)。技能本身无需安装任何额外依赖,仅使用 Python 标准库。
  2. 在技能市场安装技能:在所用 AI 技能平台的技能市场或技能库中,按技能名称「API文档自动生成Skill」、英文名 api-doc-gen 或技能 ID 14277 检索,进入详情页点击安装 / 启用即可。具体入口路径与账号要求以官方说明为准。
  3. 在会话中启用:安装完成后,在 AI 助手/Agent 的工具或技能列表中确认该技能处于启用状态,后续对话中提到「生成 API 文档」「OpenAPI」「Swagger」「接口文档」「路由扫描」等关键词时即可触发。
  4. 验证是否生效:让它扫描一个已知的小项目目录,例如提示「用 api-doc-gen 扫描 ./src 生成 OpenAPI 文档」,若能返回以 "openapi": "3.0.3" 开头的 JSON 结构(或 YAML),说明技能已正常工作;也可以在本地直接执行 python scripts/generate_api_doc.py ./src 验证脚本可用性。
  5. 接入文档平台:把生成的 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 负责把该文件渲染成可交互的在线文档,两者配合使用效果最好。