api-doc-generator

如何使用此技能

扫描代码中的 API 端点，提取接口详情，并生成标准化文档。对于未明确提及 API/接口的一般文档请求，请勿触发此技能。

工作流

1. 扫描代码 - 检查当前项目或指定对象中的 Controller 类和 API 接口
2. 提取信息 - 扫描接口，收集请求 URL、方法、参数和响应信息
3. 生成文档 - 按照标准模板创建 API 文档
4. 保存输出 - 将文档保存到当前项目的 ./docs 目录

分步流程

步骤 1：扫描代码中的接口

重要：生成任何文档之前，必须先扫描代码以查找 API 接口。

1. 确定目标：

   • 询问用户要扫描整个项目还是特定的 Controller 类
   • 如果未指定目标，则扫描整个项目以查找 Controller 类
   • 常见的 Controller 模式：
     • Java：@RestController、带有 @RequestMapping 的 @Controller
     • Spring Boot：位于 controller 或 web 包中的类
     • 以 Controller.java 或 Controller.kt 结尾的文件

2. 扫描 Controller：

   • 在项目中搜索 Controller 类
   • 识别所有带有 @RestController 或 @Controller 注解的类
   • 列出所有找到的 Controller 类

3. 检查接口：

   • 对每个 Controller 类，扫描带有以下注解的方法：
     • @GetMapping、@PostMapping、@PutMapping、@DeleteMapping
     • 指定了 method 的 @RequestMapping
   • 统计找到的 API 接口总数

4. 验证：

   • 如果未找到接口，停止并告知用户：

     未找到任何接口，无法生成接口文档。请确认：
     1. 项目中是否存在 Controller 类
     2. Controller 类中是否有 @GetMapping、@PostMapping 等注解的方法
     3. 是否指定了正确的扫描路径
     

   • 如果找到接口，则继续执行步骤 2

输出：Controller 类列表及找到的接口总数。

步骤 2：提取接口信息

重要：对于每个接口，都要提取完整信息，包括 URL、方法、参数和响应。

对于找到的每个 API 接口，提取以下信息：

1. 基本信息：

   • 接口名称：方法名或注解中的描述
   • 请求方法：GET、POST、PUT、DELETE、PATCH
   • 请求 URL：包含类级别和方法级别映射的完整路径
   • Controller 类：包含包名的完整类名
   • 方法名：Java/Kotlin 方法名

2. 请求信息：

   • 路径参数：URL 路径中的参数（例如，/user/{id}）
     • 参数名、类型、必填标记、描述
   • 查询参数：查询字符串中的参数
     • 参数名、类型、必填标记、默认值、描述
   • 请求体（适用于 POST/PUT）：
     • 请求体类型（JSON、Form-data 等）
     • 字段定义：名称、类型、必填标记、描述
     • 嵌套对象结构
   • 请求头：
     • 常见请求头：Authorization、Shop-Id、Tenant-Id
     • 自定义请求头（如有）

3. 响应信息：

   • 响应类型：方法的返回类型
   • 响应结构：
     • 标准响应包装类型（例如，R<T>、ApiResponse<T>）
     • 数据对象结构
   • 响应字段：
     • 字段名、类型、描述
     • 嵌套对象字段
   • 响应示例：生成 JSON 响应示例
   • 错误响应：常见错误代码和消息

4. 其他信息：

   • 描述：来自 @ApiOperation、@Operation 或方法注释
   • 标签：来自 @Api、@Tag 注解
   • 已弃用：检查是否有 @Deprecated 注解
   • 安全性：身份验证/授权要求

输出：每个接口的结构化数据，包含提取出的所有信息。

步骤 3：生成文档

关键：按照标准模板格式生成文档。

1. 选择模板语言：

   • 询问用户偏好的语言：中文或英文
   • 如果用户未指定，请根据项目上下文（代码注释、包名等）进行判断
   • 可用模板：
     • 中文：templates/接口文档模板.md
     • 英文：templates/api-documentation-template-en.md

2. 加载模板：

   • 根据语言选择加载相应模板
   • 将其用作基本结构

3. 按模块整理：

   • 按 Controller 类或业务模块对接口分组
   • 为每个模块创建章节

4. 生成接口列表：

   • 对于中文模板：创建包含以下列的“接口一览表”：
     • 序号（序号）
     • 接口地址（接口 URL）
     • 请求方式（请求方法）
     • 说明（描述）
     • 完成情况（状态）
   • 对于英文模板：创建包含以下列的“API 接口列表”：
     • No.（序号）
     • 接口 URL
     • 方法
     • 描述
     • 状态

5. 生成接口定义： 对于每个接口，生成：

   • 接口名称：清晰、描述性强的名称
   • 接口地址：包含方法的完整 URL
   • 描述：
     • 对应的 Controller 类和方法
     • 业务功能描述
     • 业务规则（如有）
   • 请求部分：
     • 方法和 URL
     • 请求头表格
     • 路径参数表格
     • 查询参数表格
     • 请求体（如适用），包含字段定义
   • 响应部分：
     • 响应结构描述
     • 响应字段表格
     • 响应示例（JSON）
     • 错误响应示例

6. 添加标准章节：

   • 对于中文模板：
     • 统一响应结构：标准响应格式
     • 分页响应格式：分页响应格式
     • 错误码约定：错误码约定
     • 请求头规范：请求头规范
     • 注意事项：重要说明
   • 对于英文模板：
     • 标准响应结构：标准响应格式
     • 分页响应格式：分页响应格式
     • 错误码约定：错误码约定
     • 请求头规范：请求头规范
     • 重要说明：重要说明

7. 格式化文档：

   • 使用规范的 Markdown 格式
   • 确保表格格式正确
   • 为 JSON 示例添加代码块
   • 添加适当层级的标题

输出：完整的 Markdown 格式 API 文档。

步骤 4：保存文档

关键：将文档保存到当前项目的 ./docs 目录。

1. 确定输出路径：

   • 默认：./docs/api-documentation.md
   • 如果有多个模块：./docs/{module-name}-api-documentation.md
   • 询问用户是否需要自定义文件名

2. 创建目录：

   • 检查 ./docs 目录是否存在
   • 如果不存在，则自动创建

3. 保存文件：

   • 将生成的文档写入文件
   • 使用 UTF-8 编码
   • 确保换行符正确

4. 通知用户：

   • 告知用户文件的保存位置
   • 显示文件路径
   • 可选择展示文档预览

输出：文档文件已保存到 ./docs/api-documentation.md（或自定义路径）。

代码扫描指南

Java/Spring Boot 项目

Controller 识别：

• 查找使用 @RestController 或 @Controller 注解的类
• 检查类级别的 @RequestMapping
• 常见包名模式：*.controller.*、*.web.*、*.api.*

方法识别：

• 查找使用以下注解的方法：
  • @GetMapping、@PostMapping、@PutMapping、@DeleteMapping、@PatchMapping
  • @RequestMapping(method = RequestMethod.GET) 等

参数提取：

• @PathVariable：路径参数
• @RequestParam：查询参数
• @RequestBody：请求体
• @RequestHeader：请求头
• 方法签名中的参数类型

响应提取：

• 方法签名中的返回类型
• @ResponseBody 注解
• 泛型类型（例如 R<T>、Page<T>）
• 响应实体结构

Kotlin/Spring Boot 项目

与 Java 类似，但需检查：

• 用于请求和响应的 Kotlin 数据类
• 可空类型（String?、Int?）
• Kotlin 特有的注解

模板和参考资料

• templates/接口文档模板.md - 中文 API 文档模板
• templates/api-documentation-template-en.md - 英文 API 文档模板
• examples/scan-and-generate-example.md - 完整工作流示例

询问用户偏好的语言（中文/英文）。如果未指定，则根据项目上下文判断。

最佳实践

1. 从代码注解和注释中提取所有可用信息
2. 严格遵循模板结构
3. 使用规范的 JSON 格式编写贴近实际的响应示例
4. 记录常见错误场景和错误代码
5. 按模块或 Controller 类组织接口

关键词

API 文档，API 文档，生成 API 文档，扫描接口，REST API，接口文档，API 文档，生成接口文档，扫描接口