技能使用指南

api-doc-generator（API文档生成器）Skill 是什么？如何一键扫描接口生成文档？

API文档生成器Skill（api-doc-generator）能自动扫描 Spring Boot 项目 Controller，提取 URL、请求方法、参数与响应结构，按标准模板生成 Markdown 接口文档并保存到 ./docs 目录。零侵入、不改代码、双语文档模板、含接口一览表与错误码规范。本文详解安装启用方式、四步使用流程、竞品对比与典型场景，帮你把写接口文档的时间从半天压缩到几分钟，立即了解如何上手。

API文档生成器Skillapi-doc-generator
8 个章节 约 18 分钟阅读 AI 智能生成

API文档生成器Skill：扫描 Controller 自动产出标准化接口文档

  • 一句话定位：它会扫描项目中的 Controller 类，提取 URL、请求方法、参数、响应结构，按标准模板生成 Markdown 接口文档，并自动保存到项目 ./docs 目录。
  • 核心能力：4 步标准工作流——扫描代码 → 提取接口信息 → 按模板生成文档 → 保存输出，覆盖路径参数、查询参数、请求体、请求头、响应字段与错误码。
  • 触发边界明确：只有在用户明确提到"生成 API 文档 / 接口文档 / 扫描接口"时才会启用，避免与 README、代码注释等通用文档需求混淆。
  • 产出可直接交付：内置中英文两套文档模板，包含接口一览表、统一响应结构、分页格式、错误码约定与请求头规范。
  • 适合人群：后端开发者、接口联调中的前端同学、需要维护接口资产的技术负责人与测试同学。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能基本信息

项目 内容
中文名 API文档生成器Skill
英文名 api-doc-generator
技能ID 12789
类型 代码扫描 + 文档生成类技能
输出物 Markdown 格式 API 文档，默认保存至 ./docs/api-documentation.md

它解决什么问题？

在实际项目里，接口文档往往是"最该写、最没人写"的东西。常见困境有三类：

  1. 手写跟不上迭代：接口天天改，文档还停留在三个月前，前端照着旧文档联调，一个字段对不上就要反复沟通。
  2. 信息不全：只写了 URL 和方法，路径参数、请求头（如 Authorization、Shop-Id、Tenant-Id）、响应嵌套结构、错误码全靠口头确认。
  3. 格式不统一：每个开发者按自己习惯写，最后拼在一起风格各异，新人接手成本高。

这个技能的思路是把"读代码"和"写文档"这两件事交给 AI：直接以代码为唯一事实来源，扫描注解与方法签名，把接口信息提取出来，再套用固定模板输出，减少人工遗漏和风格漂移。

一键安装的思路与步骤

AI 技能的通用安装逻辑是"先具备技能运行环境，再引入技能本体，最后验证可用"。具体到本技能：

  1. 确认前提：你需要在支持 Skills 能力的 AI 编程助手/客户端中使用它（具体支持范围以官方说明为准）。同时项目应是可被扫描读取的代码仓库，Java/Spring Boot 或 Kotlin/Spring Boot 项目效果最佳。
  2. 获取技能：在技能市场、技能库或团队内部的技能目录中，按英文名 api-doc-generator 或技能ID 12789 检索并安装/启用该技能。安装入口与命令因平台而异，具体命令以官方说明为准。
  3. 确认技能文件齐全：该技能依赖内置模板与示例资源，包括 templates/接口文档模板.md（中文模板）、templates/api-documentation-template-en.md（英文模板）以及 examples/scan-and-generate-example.md（完整工作流示例）。启用后可留意这些资源是否随技能一同加载，缺失时可向技能提供方确认。
  4. 验证是否生效：在对话中直接说一句明确的触发语句，例如"帮我扫描接口生成文档"或"为这个项目的接口生成文档"。如果技能生效，AI 会先扫描 Controller 并回报"找到的 Controller 类列表 + 接口总数"；如果没有找到接口，它会提示你检查是否存在 Controller 类、是否有 @GetMapping/@PostMapping 等方法、扫描路径是否正确。看到这个扫描反馈，就说明技能已经正常工作。
  5. 首次运行建议：第一次先指定单个 Controller 或单个模块试跑，确认输出结构和字段定义符合团队习惯，再扩大到全项目扫描。

该技能的主要功能和特点

  • Controller 智能识别：自动识别带 @RestController、@Controller 注解的类，支持类级 @RequestMapping，并可按 *.controller.*、*.web.*、*.api.* 等常见包路径定位目标。
  • 接口方法扫描：识别 @GetMapping、@PostMapping、@PutMapping、@DeleteMapping、@PatchMapping 以及 @RequestMapping(method = ...) 形式的方法，并统计接口总数。
  • 参数体系完整提取：区分 @PathVariable（路径参数）、@RequestParam（查询参数）、@RequestBody（请求体）、@RequestHeader（请求头），并读取方法签名中的参数类型、必填标记、默认值与描述。
  • 响应结构还原：支持标准响应包装器（如 R<T>、ApiResponse<T>）与分页结构（如 Page<T>），能识别泛型、嵌套对象字段，并生成示例 JSON 响应与常见错误响应。
  • 信息增强：从 @ApiOperation、@Operation、方法注释中提取描述，从 @Api、@Tag 提取标签，并检查 @Deprecated 标记已弃用接口、标注鉴权要求。
  • 双语文档模板：内置中英文两套模板，结构一致、仅语言不同；未指定语言时，可从代码注释、包名等项目上下文推断。
  • 标准化章节：文档包含文档概览（版本历史、责任表）、接口一览表、接口定义、统一响应结构、分页响应格式、错误码约定、请求头规范、注意事项。
  • 自动落盘：自动检查并创建 ./docs 目录，以 UTF-8 编码写入文件；多模块场景支持按模块拆分为 ./docs/{模块名称}-api-documentation.md。
  • 边界清晰、避免误触发：仅在明确提及 API 文档/接口文档/扫描接口时启用，不会因为一句笼统的"生成文档"就擅自动手。

和普通工具比强在哪？ 传统注解式文档工具（如 Swagger 系）需要在代码里长期维护注解、依赖运行时启动；纯手写文档依赖人的自觉性。这个技能走的是"读代码 → 出文档"的离线路径，不要求你改代码、不要求服务跑起来，产出的是可直接进 Git、可评审的 Markdown 文件。

如何使用该技能？

以下按技能定义的 4 步工作流展开，并给出可直接参考的调用示例。

步骤 1：用明确的语句触发技能

直接用带"接口文档/API文档"字样的说法发起请求。可用触发语句示例：

  • “帮我扫描接口生成文档”
  • “为这个项目的接口生成文档”
  • “创建 API 文档”
  • “生成接口文档”

注意：只说"生成文档"这类通用表述不会触发该技能。同时，README 生成、代码注释生成、用户手册编写等也都不会触发它——这是设计上的刻意约束。

步骤 2：确认扫描范围

技能会先问你：是扫描整个项目，还是只扫某个 Controller 类。示例对话：

你：帮我扫描接口生成文档，只扫订单模块。 技能：好的，我将扫描订单相关 Controller，先定位类与接口数量。

如果未指定范围，默认扫描全项目 Controller。扫描完成后，它会输出 Controller 类列表与接口总数。若数量为 0，会给出三类排查建议（是否存在 Controller 类、方法上是否有映射注解、扫描路径是否正确），此时应暂停并修正范围，而不是强行生成空文档。

步骤 3：审阅信息提取结果

这一步技能会为每个接口整理结构化信息，建议重点核对：

  • 请求 URL 是否为"类级映射 + 方法级映射"拼接后的完整路径；
  • 路径参数/查询参数的类型与必填标记是否正确；
  • 请求体的字段定义与嵌套结构是否完整；
  • 响应包装器与数据对象字段是否与实际返回一致；
  • 是否有接口被标记为已弃用、是否有鉴权要求。

步骤 4：选择文档语言并生成

技能会询问你偏好中文还是英文模板；若未指定，则从项目上下文推断。选定后按模板生成：

  • 接口一览表（中文模板列：序号 / 接口地址 / 请求方式 / 说明 / 完成情况）；
  • 每个接口的详细定义（请求部分 + 响应部分 + JSON 示例 + 错误响应示例）；
  • 统一响应结构、分页格式、错误码约定、请求头规范、注意事项。

步骤 5：保存与确认

默认保存到 ./docs/api-documentation.md；目录不存在会自动创建。多模块时按模块拆分命名。技能会告知文件路径，并可选展示文档预览。你也可以要求自定义文件名。

输入输出示例（示意）

输入：帮我扫描接口生成文档，语言用中文

输出（节选示意）：

## 接口一览表

| 序号 | 接口地址 | 请求方式 | 说明 | 完成情况 |
| --- | --- | --- | --- | --- |
| 1 | /api/order/{id} | GET | 查询订单详情 | 已完成 |
| 2 | /api/order | POST | 创建订单 | 已完成 |

### 查询订单详情

- 接口地址：GET /api/order/{id}
- 描述：对应 OrderController#getOrderById，按订单ID查询详情

请求参数（路径参数）：
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | Long | 是 | 订单ID |

响应示例：
{ "code": 0, "message": "success", "data": { "id": 1001, "status": "PAID" } }

文件保存位置：./docs/api-documentation.md。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
api-doc-generator（本技能） 代码扫描式离线文档生成 扫描 Controller、提取参数与响应、按模板生成 Markdown 并落盘 ./docs 需在支持 Skills 的 AI 助手中启用，具体方式以官方说明为准；无需改代码、无需启动服务 已有 Spring Boot 项目需要快速补齐接口文档、交付给前后端联调 优势：零侵入、产出可入库的 Markdown、模板结构统一；不足：以静态扫描为主，运行时动态行为（如拦截器改写、动态路由）无法完全体现
Swagger / OpenAPI（如 springdoc） 运行时代码优先的接口描述规范 注解描述接口，生成在线交互式文档与 OpenAPI 文件 需引入依赖、加注解、启动服务；有版本兼容与配置成本 需要在线调试、Mock、作为长期 API 契约 优势：生态成熟、可交互调试、契约可持续维护；不足：注解维护成本高、需改代码、文档质量依赖开发者注解习惯
Apifox / YApi 等接口协作平台 团队级接口协作与 Mock 接口管理、Mock、自动化测试、团队协作 需部署/注册账号、手动录入或导入接口 多人协作、测试驱动、需要 Mock 与自动化 优势：协作与测试闭环完整；不足：接口信息需人工录入或依赖导入，与代码存在同步漂移风险
手写 Markdown / README 最轻量的文档方式 完全人工撰写 零门槛 接口极少的小项目、一次性交付 优势：灵活、无依赖；不足：易过时、字段易漏、格式不统一、维护全靠自觉

选择建议：如果团队已有稳定的 Swagger 生态且需要在线调试，继续用它；如果代码已写好但文档长期缺失、又不想为写文档改代码，用本技能先把"底稿"扫出来最划算；如果强调多人协作与 Mock 测试，可把本技能产出的 Markdown 作为初始素材导入协作平台。

该技能的典型应用场景与实际体验情况

场景一：接手遗留项目，接口文档为零

  • 角色与痛点：新入职后端或接手外包项目的开发者，面对几十个 Controller、注释稀疏，不知道有哪些接口、参数怎么传。
  • 使用方式：直接说"帮我扫描整个项目的接口生成文档"，先拿到 Controller 列表与接口总数，再按模块分批生成。
  • 实际体验：上手难度低，几乎不需要学习成本，关键在于触发语句要带"接口文档"字样。效果上能快速把"接口全景"摊开，尤其接口一览表对摸清系统边界很有帮助。注意事项：若项目未使用标准注解（例如用自定义路由），扫描结果可能不完整，需要人工补充。

场景二：前后端联调前的文档交付

  • 角色与痛点：后端改完接口，前端催文档；口头描述字段容易歧义，尤其是嵌套对象和错误码。
  • 使用方式：扫描对应模块 Controller，选择中文模板生成，产出包含请求头规范、响应字段表和 JSON 示例的文档。
  • 实际体验：字段表和示例 JSON 是提升沟通效率的关键，能显著减少"这个字段啥类型""错误码 5001 是什么意思"的反复问答。注意事项：生成后建议后端本人快速扫一遍，确认 @Deprecated 接口与鉴权要求是否标注准确。

场景三：多模块微服务项目的文档治理

  • 角色与痛点：技术负责人希望各服务文档格式统一，但各团队写法五花八门。
  • 使用方式：统一要求使用本技能的标准模板，多模块时按 ./docs/{模块名称}-api-documentation.md 拆分输出，形成一致的目录结构。
  • 实际体验：模板固定带来的统一性是最大收益，文档可直接进 Git 参与评审、跟随版本迭代。注意事项：建议把"接口变更后重新生成并提交文档"写进团队流程，否则文档仍会随时间漂移。

场景四：Kotlin / Spring Boot 项目补文档

  • 角色与痛点：Kotlin 项目使用数据类承载请求响应，可空类型（String?、Int?）在文档里容易表达不清。
  • 使用方式：技能对 Kotlin 场景做了适配，会结合数据类与可空类型提取字段信息，生成时注意核对可空字段的必填标记。
  • 实际体验：整体流程与 Java 一致，可空类型与数据类的识别是加分项；建议生成后对可空字段做一次抽查，确保必填/非必填的表述符合业务预期。

该技能能为用户带来的价值

  • 把"写文档"从几小时压缩到几分钟：传统做法是逐个 Controller 翻代码、手抄 URL 和参数、再排版成表格；本技能把扫描、提取、排版、落盘串成一条自动链路，人工只需审阅与微调。对于一个几十接口的模块，节省的时间从"半天级"降到"分钟级"。
  • 降低文档门槛，让"不擅长写文档的人"也能交付合格产出：模板固定了章节结构（接口一览表、统一响应结构、分页格式、错误码约定、请求头规范），不需要记忆格式规范，也不会漏掉关键小节。
  • 减少联调返工：请求头规范（Authorization、Shop-Id、Tenant-Id 等）与错误响应示例被显式记录下来，把"上线后才发现漏传 header"的风险前移到文档阶段。
  • 产出可沉淀、可版本化的资产：Markdown 文件保存到 ./docs 并进入代码仓库，可以随代码一起评审、回溯、对比差异，长期形成可继承的接口资产。
  • 边界清晰，不打扰日常开发：只在明确提及 API 文档时触发，不会在你只是想要一段代码注释或 README 时擅自生成一堆文件，避免噪音。
  • 长期价值：接口文档是团队协作的基础设施。当"生成文档"的成本接近于零，团队才更可能持续维护它，从而降低人员流动带来的知识流失。

常见问题 FAQ

Q1：这个技能怎么安装？装完怎么确认能用？

A：在支持 Skills 的 AI 助手中，按英文名 api-doc-generator 或技能ID 12789 在技能市场/技能目录中检索并启用即可，具体入口与命令因平台不同，以官方说明为准。验证方法：直接说"帮我扫描接口生成文档"，若技能生效，它会先返回 Controller 类列表与接口总数；若提示"未找到任何接口"，按提示检查 Controller 类、映射注解和扫描路径。

Q2：是不是任何"生成文档"的请求都会触发它？

A：不是，而且这是刻意的设计。技能明确规定：只有在明确提及"API文档"“接口文档”“扫描接口”"记录 API"时才触发。像 README 生成、代码注释生成、用户指南、技术规范，以及只说"生成文档"这种过于笼统的表述，都不会触发。这样可以避免在不相关的文档任务里被误调用。

Q3：收费吗？有什么使用限制？

A：本次提供的技能信息中未包含定价信息，是否收费以及额度限制以官方说明为准。技能附带 LICENSE.txt，完整条款在该文件中，商用或二次分发前建议先阅读。功能层面，它的扫描对象以 Java/Spring Boot 与 Kotlin/Spring Boot 的 Controller 为主。

Q4：适合谁用？前端或测试同学能用吗？

A：最直接的使用者是后端开发者——代码在手，一句话就能出文档。前端和测试同学同样受益：可以请后端触发一次生成，拿到包含参数表、字段说明与 JSON 示例的文档用于联调与用例设计。技术负责人则可以用它统一团队的文档格式。

Q5：和 Swagger / Apifox 这类工具怎么选？

A：看需求侧重。需要在线调试、Mock、自动化测试和长期 API 契约管理，选 Swagger 系或 Apifox/YApi 这类协作平台；已经写好代码但文档长期缺位、又不想为写文档去改代码或启动服务，用本技能最快出底稿。两者并不冲突：可以先用本技能扫出 Markdown 底稿，再导入协作平台继续维护。

Q6：生成结果不完整怎么办？

A：先确认接口是否使用了标准注解（@RestController/@Controller + @GetMapping 等）。若确认存在但未被识别，可缩小到单个 Controller 重新扫描定位问题。另外，静态扫描无法反映运行时动态行为（如拦截器改写响应、动态路由），这类内容需要在生成后人工补充。