CodeBuddy接口文档生成与整理方法

编写接口文档看似简单，实则需要细致处理。手动录入路径、参数、响应体不仅耗时，还容易遗漏字段长度、格式校验、必填等约束条件。CodeBuddy 提供三种生成方式，覆盖从零开始、代码已有注释以及直接扫描整个 Controller 的场景。以下逐一拆解。

用自然语言指令即时生成Markdown接口文档

这是最直接的方式，适合连注释都没写、或者需求刚确定就要出文档的情况。只需一句话描述，CodeBuddy 即可补齐路径、动词、请求体结构、状态码和示例。

具体操作：在 CodeBuddy CLI 交互模式下输入“生成用户登录接口文档：POST /api/v1/auth/login，请求体含 email（字符串，必须为有效邮箱格式）、password（字符串，长度6-20位），返回200成功响应{“token”: “string”, “expiresIn”: 3600}，401返回{“error”: “invalid_credentials”}”。随后 AI 将输出完整的 Markdown 内容，包含标题、请求 URL、方法、请求头说明、参数表格、状态码列表以及两个 JSON 示例块。直接复制粘贴到项目根目录下的 docs/api-login.md 即可。

基于JSDoc注释自动生成OpenAPI 3.0 YAML

对于 Node.js/Express 项目，若代码中已写好带 @openapi 标签的 JSDoc 注释，可采用第二种方式。CodeBuddy 会解析这些注释并补全 OpenAPI 必需的字段，避免手写 YAML 时遗漏 components 或 securityDefinitions。

有两种途径可选：

方法一：CLI 命令导出

首先确保每个路由函数上方都有类似这样的注释块：
/**
* @openapi
* /api/v1/orders:
* post:
* summary: 创建订单
* requestBody:
* required: true
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/CreateOrderRequest'
*/

然后在项目根目录执行：codebuddy doc generate --format openapi3 --output openapi.yaml。生成后务必检查 openapi.yaml 是否包含 components.schemas.CreateOrderRequest 定义——若缺失，说明 @openapi 块被忽略，通常是注释缩进或空行不符合 swagger-jsdoc 规范。

方法二：IDE 内右键触发

在 VS Code 中打开含注释的文件（如 routes/order.js），选中整个 @openapi 注释块，右键选择「CodeBuddy → Export as OpenAPI」，再选 YAML 格式导出即可，省去命令行步骤。

引用现有Controller类批量生成结构化文档

这是 Spring Boot 项目的专属功能。无需逐行写注释，CodeBuddy 通过静态分析直接提取 @RequestMapping、@RequestParam、@RequestBody 等注解信息，并能关联 DTO 类型定义。

操作分四步：

第一步，确认 Controller 类位于 src/main/java/com/example/demo/controller/ 下，且项目已启用 @ComponentScan 或 @SpringBootApplication 扫描该包路径。路径错误则无法生成。

第二步，在 CodeBuddy IDE 中点击顶部菜单栏「Tools」→「Generate API Docs from Controllers」，弹窗内输入：/generate-api-doc from OrderController, UserController。

第三步，系统自动填充基础路径和参数名后，需在右侧面板手动补充每个 @RequestParam 字段的“是否必填”和“业务含义”。例如 page 字段填写“必填否”和“分页页码，从1开始，默认为1”。这一步直接影响文档可用性。

第四步，点击「Export as Markdown」，保存为 docs/api-reference.md。打开文件确认每个接口都包含「请求示例」和「响应样例」区块，且字段类型与实际情况一致即可。