CodeBuddy生成OpenAPI文档失败的主因是注释不规范、插件未启用或提示词缺约束；可通过四路径解决：一、源码注释+AI解析；二、自然语言直生成；三、IDE插件实时同步；四、自定义指令批量生成。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用CodeBuddy为Node.js或Java项目生成OpenAPI 3.0规范文档时发现输出缺失路径定义、参数类型错误或响应结构不完整，则可能是由于注释格式不标准、插件未启用或自然语言提示词缺乏关键约束。以下是实现该目标的多种操作路径：
一、基于源码注释+AI解析生成OpenAPI文档
该方法依赖CodeBuddy对代码中结构化注释（如Express路由函数旁的JSDoc、Spring Boot Controller中的Swagger兼容注解）进行语义理解，自动提取HTTP方法、路径、请求体字段与响应Schema，并补全OpenAPI 3.0必需字段。
1、在Express路由处理函数上方添加符合swagger-jsdoc规范的JSDoc注释，包含@openapi标签及method、path、summary、parameters、responses等子字段。
2、确保项目根目录存在swaggerOptions配置对象，其中apis字段明确指向含注释的JS文件路径（例如./routes/*.js）。
3、向CodeBuddy提交指令：“根据当前项目中的JSDoc注释，生成符合OpenAPI 3.0规范的YAML文档，要求保留所有@openapi块内容，自动推导requestBody.schema和responses.200.content.application/json.schema”。
4、接收CodeBuddy返回的完整YAML字符串，将其保存为openapi.yaml，并通过Swagger UI加载验证字段嵌套层级是否正确。
二、通过自然语言描述直生成OpenAPI Schema
该方法绕过代码解析环节，直接将业务需求转化为结构化OpenAPI定义，适用于接口设计先行阶段或原型评审场景，要求提示词中显式声明HTTP方法、路径、参数约束及响应示例。
1、输入精确提示词：“生成符合OpenAPI 3.0规范的YAML文档，描述以下接口：POST /api/v1/alerts，请求体为JSON，包含type（字符串，枚举值为'FLOOD'、'WIND'、'TIDE'）、location（GeoCoordinate对象，含type和coordinates数组）、triggerTime（ISO8601字符串）；响应状态码201，返回{“alertId”: “string”, “createdAt”: “string”}，并为每个字段提供example值。”
2、调用CodeBuddy内置的大模型API，设置temperature=0.1以保障确定性输出，强制response_format为yaml。
3、提取返回内容中```yaml与```之间的纯文本，剔除任何解释性语句或Markdown容器标记。
4、使用Swagger Editor在线校验生成结果，重点确认components.schemas.GeoCoordinate必须正确定义且被 requestBody 引用，否则将导致UI渲染失败。
CodeBuddy Code CLI 的安装、配置与使用指南。CodeBuddy Code 是腾讯推出的 AI 驱动 CLI 编程助手，支持自然语言驱动开发。 - 必备触发词：CodeBuddy, codebuddy, AI CLI, Tencent AI coding, @tencent-ai/codebuddy-code, terminal AI assistant - 适用场景：安装 CodeBuddy CLI、配置 CodeBuddy、使用 CodeBuddy 命令、排查 CodeBuddy 问题
三、对接IDE插件实时同步文档
该方法将CodeBuddy能力集成至开发环境，在编写接口逻辑的同时触发文档生成，确保代码变更与OpenAPI定义始终保持一致，避免人工维护导致的版本漂移。
1、在VS Code中安装CodeBuddy官方扩展，并在settings.json中启用"codebuddy.autoGenerateOpenapi": true。
2、打开一个已定义app.post()路由的JS文件，将光标置于路由回调函数内部，按下Ctrl+Shift+P调出命令面板。
3、选择“CodeBuddy: Generate OpenAPI Spec from Current Route”，插件将自动分析req.body、req.params、res.status()调用及返回对象结构。
4、生成的OpenAPI片段将插入至项目根目录下的openapi.json对应paths节点下，若该路径已存在，则执行深度合并而非覆盖，保留原有description与deprecated标记。
四、利用自定义指令一键触发批量生成
该方法通过预设结构化提示词模板，将重复性文档生成任务封装为可复用的斜杠指令，支持多接口批量处理与格式一致性控制，适用于每日构建流程集成。
1、在项目.codebuddy/commands目录下创建generate-openapi.md文件，定义指令元信息：--description:"? 生成OpenAPI文档 - 根据指定路由文件批量生成YAML格式接口定义"
2、在提示词骨架中声明角色为“资深OpenAPI架构师”，背景限定为“当前项目使用Express 4.x，所有接口返回统一格式{code, message, data}”。
3、任务目标明确要求：“从./routes/alert.js与./routes/device.js中提取全部POST/GET接口，为每个参数生成allowEmptyValue: false与example，响应data字段必须引用components.schemas.BaseResponse”。
4、执行/codebuddy generate-openapi --files ./routes/alert.js,./routes/device.js，输出自动写入docs/openapi.generated.yaml且跳过人工校验步骤。
