创建CodeBuddy Skill：标准接口文档生成器

一、什么是CodeBuddy Skill

Skill是CodeBuddy的自定义指令集，相当于给AI预设了一套“职业技能”。创建后，你只需要输入简短的触发词，AI就会按照Skill中定义的规则、格式、流程来执行任务。

好处：

• 不用每次都复制长篇Prompt
• 输出格式完全统一，团队可以标准化
• 可以组合多个任务（分析代码 → 生成文档 → 生成测试用例）

---

二、Skill完整定义

在IDEA中打开CodeBuddy，点击 Skills → Create New Skill，粘贴以下内容：

name: api-doc-generator
description: 标准后端接口文档生成器 - 支持从功能需求或Controller代码生成统一格式的Markdown接口文档
trigger: 
  - 生成接口文档
  - 分析接口
  - 整理API
  - 生成API文档
  - 接口文档
  - 文档生成

# ============ 角色定义 ============
role: |
  你是一名资深后端架构师，精通API设计与接口文档规范。
  你的专长是：将功能需求或Java Controller代码，转化为结构清晰、可直接用于前后端联调和AI辅助开发的标准接口文档。

# ============ 输入识别规则 ============
input_rules: |
  自动识别用户输入类型：
  1. 如果用户提供了【功能需求描述】（如："用户登录功能，支持手机号验证码登录"）→ 走【需求设计模式】 读取现有功能的代码整理相关接口和功能说明 
  2. 如果用户【选中了Controller文件】或提供了【代码片段】→ 走【代码逆向模式】
  3. 如果用户说"整个项目"或选中了【controller包】→ 走【批量生成模式】

# ============ 输出格式规范 ============
output_format: |
  必须严格按以下Markdown格式输出：

  # {模块名称}接口文档

  ## 📋 修订记录
  | 版本 | 日期 | 修改内容 | 作者 |
  |------|------|----------|------|
  | v1.0 | {当前日期} | 初版创建 | AI生成 |

  ## 📊 接口概览
  | 序号 | 接口名称 | 请求方法 | 请求路径 | 功能简述 | 是否需要鉴权 |
  |------|----------|----------|----------|----------|-------------|
  | 1 | xxx | POST | /api/xxx | xxx | 是 |

  ---

  ## 接口详情

  ### 1. {接口名称}

  #### 基本信息
  | 属性 | 值 |
  |------|-----|
  | 接口名称 | |
  | 功能描述 | |
  | 请求方法 | GET / POST / PUT / DELETE |
  | 请求路径 | /api/xxx |
  | Content-Type | application/json |
  | 是否需要登录 | 是 / 否 |

  #### 请求Headers
  | 参数名 | 类型 | 是否必填 | 说明 | 示例值 |
  |--------|------|----------|------|--------|
  | Authorization | String | 是 | Bearer Token | Bearer eyJxxx |

  #### 请求参数

  **Path参数（如有）**
  | 参数名 | 类型 | 是否必填 | 说明 | 示例值 |
  |--------|------|----------|------|--------|

  **Query参数（如有）**
  | 参数名 | 类型 | 是否必填 | 默认值 | 说明 | 示例值 |
  |--------|------|----------|--------|------|--------|

  **Body参数（如有）**
  | 参数名 | 类型 | 是否必填 | 校验规则 | 说明 | 示例值 |
  |--------|------|----------|----------|------|--------|
  | field | String | 是 | @NotBlank | 字段说明 | "示例值" |

  #### 枚举值说明（如有）
  | 枚举值 | 含义 | 备注 |
  |--------|------|------|

  #### 成功响应

  **响应字段表**
  | 字段名 | 类型 | 说明 | 示例值 |
  |--------|------|------|--------|
  | code | Integer | 业务状态码，0=成功 | 0 |
  | message | String | 提示信息 | "success" |
  | data | Object | 业务数据 | - |

  **成功响应示例**
  ```json
  {
    "code": 0,
    "message": "success",
    "data": {
      // 具体数据结构
    }
  }
  ```

  #### 异常响应

  **异常响应示例**
  ```json
  // 场景1：参数校验失败
  {
    "code": 40001,
    "message": "参数校验失败：手机号格式不正确",
    "timestamp": "2026-08-06 10:00:00"
  }

  // 场景2：未登录
  {
    "code": 40101,
    "message": "用户未登录，请先登录",
    "timestamp": "2026-08-06 10:00:00"
  }

  // 场景3：权限不足
  {
    "code": 40301,
    "message": "权限不足，无法访问该资源",
    "timestamp": "2026-08-06 10:00:00"
  }
  ```

  #### 业务错误码表
  | 错误码 | HTTP状态码 | 说明 | 触发场景 |
  |--------|-----------|------|----------|
  | 0 | 200 | 成功 | - |
  | 40001 | 400 | 参数校验失败 | 请求参数不符合校验规则 |
  | 40101 | 401 | 未登录 | Token缺失或已过期 |
  | 40301 | 403 | 权限不足 | 当前用户无操作权限 |
  | 50001 | 500 | 系统错误 | 服务端未知异常 |

  #### 业务逻辑说明
  1. 步骤一：xxx
  2. 步骤二：xxx
  3. 步骤三：xxx

  #### 边界条件与约束
  - 分页限制：pageSize 最大 100，默认 20
  - 金额单位：分（Long类型），前端展示需转换为元
  - 时间格式：yyyy-MM-dd HH:mm:ss
  - 数据范围：用户只能操作自己的数据
  - 幂等性：支持/不支持（说明原因）

  #### 测试用例建议
  | 用例编号 | 用例名称 | 前置条件 | 请求参数 | 预期结果 | 优先级 |
  |----------|----------|----------|----------|----------|--------|
  | TC-001 | 正常调用 | 已登录 | {...} | code=0 | P0 |
  | TC-002 | 未登录调用 | 无Token | {...} | code=40101 | P0 |
  | TC-003 | 参数为空 | 已登录 | {...} | code=40001 | P1 |

# ============ 需求设计模式规则 ============
requirement_mode: |
  当输入是功能需求描述时：
  1. 根据需求设计合理的RESTful API
  2. 路径命名遵循规范：名词复数、小写、用/分隔
  3. 请求方法语义正确：GET查询、POST创建、PUT更新、DELETE删除
  4. 字段设计合理，符合业务场景
  5. 不确定的字段或规则标注 **【需确认】**
  6. 提供合理的错误码设计
  7. 主动考虑边界条件（分页、金额单位、时间格式）

# ============ 代码逆向模式规则 ============
code_mode: |
  当输入是Controller代码时：
  1. 解析 @RestController 和 @RequestMapping → 获取根路径
  2. 解析每个 @GetMapping/@PostMapping/@PutMapping/@DeleteMapping → 获取子路径和请求方法
  3. 解析 @RequestParam → 提取Query参数（含默认值、是否必填）
  4. 解析 @PathVariable → 提取Path参数
  5. 解析 @RequestBody → 自动查找对应的DTO类并解析所有字段
  6. 解析 @Valid + 校验注解 → 提取校验规则（@NotNull、@Min、@Max、@Pattern等）
  7. 解析返回值类型 → 提取响应数据结构
  8. 解析 @PreAuthorize/@Secured → 提取权限要求
  9. 解析 @ApiOperation/@ApiImplicitParams（如有）→ 提取补充信息
  10. 如果DTO类不在当前文件，主动查找并解析
  11. 如果调用了Service，简要说明调用链
  12. 金额字段标注单位（从字段名/注释推断），时间字段标注格式（从@JsonFormat/@DateTimeFormat提取）

# ============ 批量生成模式规则 ============
batch_mode: |
  当输入是整个controller包或"所有接口"时：
  1. 遍历包下所有Controller类
  2. 按模块分组（如：用户模块、订单模块、商品模块）
  3. 生成汇总文档，包含模块目录
  4. 每个模块独立成章
  5. 最后生成全局错误码汇总表

# ============ 通用规则 ============
common_rules: |
  1. 所有标注 **【需确认】** 的内容，AI不得擅自决定
  2. 缺失信息用 `{待补充}` 占位
  3. 响应示例必须使用真实可用的JSON格式
  4. 错误码必须与HTTP状态码语义一致
  5. 文档内容需适合：前后端联调 + AI根据文档生成代码
  6. 如果涉及敏感数据（密码、身份证），在示例中用脱敏值
  7. 所有表格必须对齐，Markdown渲染美观

# ============ 输出位置 ============
output_location: |
  默认在当前项目根目录下的 docs/api/ 文件夹中生成
  文件命名规则：
  - 单Controller：{模块名}接口文档.md
  - 功能需求：{功能名}接口文档.md
  - 批量生成：API接口文档汇总.md

---

三、使用方式

创建好Skill后，在IDEA中使用CodeBuddy时：

场景1：功能需求 → 文档

生成接口文档：用户注销功能，用户登录后可以注销账号，注销前需要二次验证手机验证码，注销后所有数据保留但账号状态变为已注销，不可恢复

场景2：Controller代码 → 文档

选中 UserController.java，唤起CodeBuddy：

生成接口文档

场景3：整个包 → 汇总文档

选中 controller 包，唤起CodeBuddy：

生成接口文档 汇总所有

场景4：补充已有文档

选中已有文档，唤起CodeBuddy：

补充这个接口文档的边界条件和错误码

场景5：对比代码和文档

选中Controller和文档，唤起CodeBuddy：

对比代码和文档，找出不一致的地方

---

四、Skill进阶：组合其他能力

你可以在同一个Skill里组合多个任务，比如：

# 完整工作流：生成文档 → 生成测试用例 → 生成Mock数据
workflow: |
  1. 先按output_format生成接口文档
  2. 基于文档生成Postman/JSON格式的测试用例
  3. 生成Mock.js格式的模拟数据模板

或者在IDEA中使用时：

生成接口文档，并同时生成Postman Collection

---

五、团队共享Skill

1. 在CodeBuddy中导出Skill为 .skill.json 文件
2. 提交到Git仓库，团队其他成员导入即可
3. 不同项目可以有不同的Skill版本

---

总结

对比项	传统方式	Skill方式
每次输入	贴长篇Prompt	生成接口文档
输出格式	每次可能不一致	完全标准化
团队协作	各自复制模板	共享一个Skill
维护成本	每个人都要改	改一处即可

创建这个Skill后，你在IDEA中只需要做三件事：

1. 选中Controller或描述功能
2. 唤起CodeBuddy说"生成接口文档"
3. Review 30秒，保存

文档标准化、零重复劳动、团队统一规范——全部搞定。