name: api-doc-generator description: | 提供通过扫描代码接口、提取请求/响应信息并创建标准化API文档的全面指导。仅当用户明确提及生成API文档、创建API文档、扫描接口或记录API时使用。该技能扫描Controller类，提取接口信息（URL、方法、参数、响应），并遵循标准模板生成文档。对于没有明确提及API文档的通用文档请求，请勿触发此技能。 license: 完整条款在LICENSE.txt中

何时使用此技能

关键：此技能应仅在用户明确提及生成API文档、创建API文档、扫描接口或记录API时触发。

始终在用户提及以下内容时使用此技能：

生成API文档（明确提及“API文档”或“API文档”）
从代码创建API文档
扫描接口以生成文档
记录REST API
生成接口文档（明确提及“接口文档”）
扫描接口生成文档（扫描接口以生成文档）
创建API文档（创建API文档）

触发短语包括：

“生成接口文档”（生成API文档） - 必须包含“接口文档”
“扫描接口生成文档”（扫描接口以生成文档）
“创建API文档”（创建API文档）
“为接口生成文档”（为接口生成文档）
“接口文档生成”（API文档生成）

请勿为此触发此技能：

未提及API/接口的通用文档请求
代码注释生成
README文件生成
其他类型的文档（用户指南、技术规范等）
“生成文档”而不包含“接口”或“API”（过于通用）

如何使用此技能

关键：此技能应仅在用户明确提及生成API文档时触发。对于没有API上下文的通用文档请求，请勿触发。

工作流程概述

此技能遵循系统化的4步工作流程：

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

逐步流程

步骤1：扫描代码以查找接口

关键：在生成任何文档之前，您必须扫描代码以找到API接口。

识别目标：
- 询问用户是否要扫描整个项目或特定的Controller类
- 如果未指定目标，则扫描整个项目以查找Controller类
- 常见的Controller模式：
  - Java：@RestController、@Controller与@RequestMapping
  - Spring Boot：controller或web包中的类
  - 以Controller.java或Controller.kt结尾的文件
扫描Controller类：
- 在项目中搜索Controller类
- 识别所有带有@RestController或@Controller注解的类
- 列出所有找到的Controller类
检查接口：
- 对于每个Controller类，扫描带有以下注解的方法：
  - @GetMapping、@PostMapping、@PutMapping、@DeleteMapping
  - @RequestMapping带有方法规范
- 计算找到的API接口总数

验证：

如果未找到任何接口，停止并通知用户：

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

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

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

步骤2：提取接口信息

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

对于每个找到的API接口，提取：

基本信息：
- 接口名称：方法名称或注解中的描述
- 请求方法：GET、POST、PUT、DELETE、PATCH
- 请求URL：包括类级和方法级映射的完整路径
- Controller类：带包的完整类名
- 方法名称：Java/Kotlin方法名称
请求信息：
- 路径参数：URL路径中的参数（例如/user/{id}）
  - 参数名称、类型、必需标志、描述
- 查询参数：查询字符串中的参数
  - 参数名称、类型、必需标志、默认值、描述
- 请求体（用于POST/PUT）：
  - 正文类型（JSON、Form-data等）
  - 字段定义：名称、类型、必需标志、描述
  - 嵌套对象结构
- 请求头：
  - 常见头：Authorization、Shop-Id、Tenant-Id
  - 自定义头（如果有）
响应信息：
- 响应类型：方法的返回类型
- 响应结构：
  - 标准响应包装器（例如R<T>、ApiResponse<T>）
  - 数据对象结构
- 响应字段：
  - 字段名称、类型、描述
  - 嵌套对象字段
- 响应示例：生成示例JSON响应
- 错误响应：常见错误代码和消息
附加信息：
- 描述：来自@ApiOperation、@Operation或方法注释
- 标签：来自@Api、@Tag注解
- 已弃用：检查@Deprecated注解
- 安全性：身份验证/授权要求

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

步骤3：生成文档

关键：遵循标准模板格式生成文档。

选择模板语言：
- 询问用户偏好的语言：中文或英文
- 如果未指定，则从项目上下文（代码注释、包名等）中检测
- 可用模板：
  - 中文：templates/接口文档模板.md
  - 英文：templates/api-documentation-template-en.md
加载模板：
- 根据语言选择加载适当的模板
- 将其用作基础结构
按模块组织：
- 按Controller类或业务模块分组接口
- 为每个模块创建部分
生成接口列表表：
- 对于中文模板：创建“接口一览表”，列包括：
  - 序号（序列号）
  - 接口地址（接口URL）
  - 请求方式（请求方法）
  - 说明（描述）
  - 完成情况（状态）
- 对于英文模板：创建“API接口列表”，列包括：
  - No.（序列号）
  - 接口URL
  - 方法
  - 描述
  - 状态
生成接口定义：对于每个接口，生成：
- 接口名称：清晰、描述性的名称
- 接口地址：带方法的完整URL
- 描述：
  - 对应的Controller类和方法
  - 业务功能描述
  - 业务规则（如果有）
- 请求部分：
  - 方法和URL
  - 头表
  - 路径参数表
  - 查询参数表
  - 请求体（如果适用）与字段定义
- 响应部分：
  - 响应结构描述
  - 响应字段表
  - 响应示例（JSON）
  - 错误响应示例
添加标准部分：
- 对于中文模板：
  - 统一响应结构：标准响应格式
  - 分页响应格式：分页响应格式
  - 错误码约定：错误代码约定
  - 请求头规范：请求头规范
  - 注意事项：重要注意事项
- 对于英文模板：
  - 标准响应结构：标准响应格式
  - 分页响应格式：分页响应格式
  - 错误代码约定：错误代码约定
  - 请求头规范：请求头规范
  - 重要注意事项：重要注意事项
格式化文档：
- 使用适当的Markdown格式化
- 确保表格式正确
- 包括JSON示例的代码块
- 添加适当的标题层次

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

步骤4：保存文档

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

确定输出路径：
- 默认：./docs/api-documentation.md
- 如果多个模块：./docs/{模块名称}-api-documentation.md
- 询问用户是否想要自定义文件名
创建目录：
- 检查./docs目录是否存在
- 如果不存在，自动创建
保存文件：
- 将生成的文档写入文件
- 使用UTF-8编码
- 确保适当的行结尾
通知用户：
- 告诉用户文件保存的位置
- 显示文件路径
- 可选显示文档预览

输出：文档文件保存到./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）：

文档概览（文档概述）
- 版本历史表
- 责任表
接口一览表（接口列表表）
- 所有接口的摘要表
接口定义（接口定义）
- 每个接口的详细定义
- 请求和响应部分
- 字段定义和示例
统一响应结构（标准响应结构）
- 标准响应格式
- 分页格式
- 错误代码
请求头规范（请求头规范）
注意事项（重要注意事项）

英文模板（templates/api-documentation-template-en.md）：

文档概述
- 版本历史表
- 责任表
API接口列表
- 所有接口的摘要表
接口定义
- 每个接口的详细定义
- 请求和响应部分
- 字段定义和示例
标准响应结构
- 标准响应格式
- 分页格式
- 错误代码
请求头规范
重要注意事项

模板选择：

询问用户偏好的语言（中文/英文）
如果未指定，从项目上下文中检测
两种模板遵循相同的结构，仅语言不同

最佳实践

完整信息：从代码中提取所有可用信息，包括注解和注释
标准格式：严格遵循模板结构
清晰描述：使用代码注释或注解中的有意义描述
示例：包括现实的响应示例
错误处理：记录常见错误场景
分组：按模块或Controller类组织接口
验证：验证所有提取的信息准确

参考文档

模板：
- templates/接口文档模板.md - 标准API文档模板（中文）
- templates/api-documentation-template-en.md - 标准API文档模板（英文）
示例：examples/scan-and-generate-example.md - 完整工作流程示例，展示如何扫描和生成API文档

关键词

英文关键词： api documentation, api docs, generate api documentation, create api docs, scan interfaces, document apis, rest api documentation, interface documentation, api doc generator, scan controllers, extract api information

中文关键词：接口文档，API文档，生成接口文档，创建接口文档，扫描接口，接口文档生成，API文档生成，接口文档生成器，扫描Controller，提取接口信息，接口文档模板

重要：所有关键词必须包含“接口文档”（API文档）或“API”以避免错误触发。通用术语如“生成文档”而不包含“接口”或“API”不应触发此技能。