CodeBuddy支持基于代码语义与结构化注解的自动文档生成，涵盖JSDoc驱动的Markdown文档、Controller批量生成的结构化文档及OpenAPI 3.0规范文件，提升协作效率与文档准确性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在开发后端服务，但接口文档仍靠手动整理、版本更新滞后、协作方频繁追问参数含义，则说明您尚未启用CodeBuddy基于代码语义与结构化注解的自动文档生成功能。该功能可将Controller方法、DTO定义、路由配置实时转化为可交付的Markdown或OpenAPI 3.0文档，避免信息断层与重复劳动。
通过JSDoc注释驱动生成Markdown文档
此方式适用于已写好Controller但尚未补充文档的Java/TypeScript项目，依赖标准注释块提取元信息，输出即用型.md文件。
1、在Controller方法上方添加多行JSDoc注释，必须包含@method、@url、@param、@returns标签，缺一不可；
2、每个@param后需注明类型、是否必填及业务含义，例如：【@param {string} userId - 用户唯一标识，长度为32位UUID字符串】；
3、@returns中必须展开响应体JSON结构，嵌套字段逐级说明，如“data.user.name: string, 用户真实姓名”；
4、选中该方法代码块→右键→“CodeBuddy → Generate API Doc”；
5、指定输出路径（建议设为docs/api/），确认后生成以接口名命名的.md文件，含请求示例与响应样例。
引用Controller类批量生成结构化文档
当项目已有完整Controller类但缺乏统一文档组织时，此方法能静态分析全部路由方法，构建带目录导航与分组逻辑的完整文档。
方法一：命令行指令触发
在对话框中输入指令：/generate-api-doc from UserController；
方法二：IDE图形界面操作
右键点击UserController.java文件→选择“CodeBuddy → Bulk Doc Generation”→勾选“Include Request Body Schema”和“Auto-link DTOs”；
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 问题
粘贴对应HTTP访问地址，如https://api.example.com/v1/users；
【必须确认请求方式并填写各端点的查询参数、请求体字段及校验规则，否则生成文档将缺失关键约束说明】；
为每个接口提供至少一组真实格式的请求参数示例与预期返回JSON，点击生成即可输出含状态码说明的完整Markdown文档。
自动生成OpenAPI 3.0规范YAML/JSON
这是对接Swagger UI、Redoc或第三方集成平台的必备步骤，CodeBuddy会深度解析框架注解与DTO类型定义，推导出标准规范文件。
第一步：确保项目已启用注解扫描能力，且@Controller/@Route声明类位于默认扫描包路径下；
第二步：执行CLI命令：codebuddy doc --format openapi3 --output ./openapi.yaml；
第三步：检查./openapi.yaml是否包含paths、components、info三大核心区块，特别验证components.schemas中DTO字段类型是否与源码一致；
第四步：若使用Spring Boot，确认pom.xml中已引入springdoc-openapi-ui依赖，否则生成的YAML无法被Swagger UI正确加载；
第五步：将生成的openapi.yaml拖入Swagger Editor，验证所有接口路径、参数、响应状态码是否完整映射。
