codebuddy支持四种swagger注解生成方式：一、提示中明确注解类型与字段；二、通过codebuddy.md全局模板统一规范；三、基于现有代码反向补全；四、cli批量注入标准模板。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用CodeBuddy为Node.js或Java项目生成接口代码时，发现缺少Swagger风格的注解以支撑后续文档自动化，可能是由于初始提示未明确要求注解类型、格式或语义粒度。以下是CodeBuddy生成Swagger API文档注解并实现接口文档自动化的多种可行路径：
一、在自然语言提示中强制声明注解类型与字段要求
CodeBuddy依据输入提示中的显式指令决定是否注入Swagger注解及覆盖范围。必须在需求描述中限定注解框架（如Swagger 2.0、OpenAPI 3.0）、目标语言（Java/TypeScript/JavaScript）及必需字段，避免模型自由发挥导致注解缺失或语义不全。
1、向CodeBuddy提交如下结构化指令：“请为Express路由文件生成支持swagger-jsdoc解析的JSDoc注释，每个接口必须包含@openapi、@description、@param（含name、in、required、schema.type）、@responses（含200、400、404的content.application/json.schema）”。
2、对Java Spring Boot项目，使用：“生成带SpringDoc OpenAPI 3.0注解的Controller方法，强制添加@Operation、@Parameter（required = true）、@ApiResponse（responseCode = "201"）和@Schema（implementation = User.class）”。
3、补充约束：“禁止使用@ApiIgnore；所有@Parameter必须指定example值；@Schema注解需覆盖嵌套对象字段，不得遗漏DTO中的List
二、通过CODEBUDDY.md全局契约注入注解模板
CodeBuddy Code模块会主动读取项目根目录下的CODEBUDDY.md文件，并将其中定义的注解模板作为默认输出规范。该方式可确保所有新生成接口统一携带完整Swagger元数据，无需每次重复描述。
1、在项目根目录创建CODEBUDDY.md文件。
2、写入以下内容：“Swagger注解规范：Node.js项目使用swagger-jsdoc兼容JSDoc，必含@openapi标签；Java项目使用SpringDoc，Controller类加@Tag，方法加@Operation；所有参数必须用@Parameter标注required属性；响应体必须用@Schema声明DTO类并启用allPropertiesRequired = true”。
3、保存后，在任意代码生成请求中省略注解说明，CodeBuddy将自动按该文件约定注入完整Swagger注解块。
三、基于已有接口代码反向补全Swagger注解
当项目已存在未注解的API实现时，CodeBuddy可通过静态分析代码结构与类型签名，推导出符合OpenAPI语义的注解内容，实现“零提示补全”，适用于遗留系统文档化改造场景。
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 问题
1、将待补全的Controller文件（如UserController.java）或Express路由文件（routes/user.js）上传至CodeBuddy编辑器。
2、右键点击类名或router.post()语句行，选择“补全Swagger注解”功能项。
3、系统自动识别@RequestMapping路径、@RequestBody参数类型、@ResponseBody返回类型，并生成对应@Operation、@Parameter、@ApiResponse及@Schema嵌套结构。
4、对检测到的GeoCoordinate等自定义类型，自动提取其字段定义并生成独立@Schema组件声明，确保OpenAPI文档可正确解析引用关系。
四、调用CLI指令批量注入标准注解模板
针对已成型但缺乏注解的多文件项目，CodeBuddy CLI提供批量处理能力，通过预设模板一次性为全部接口方法注入标准化Swagger注解，支持正则匹配路径与条件过滤，适用于CI/CD流水线集成。
1、执行命令：codebuddy inject-swagger --target ./src/controllers/**/*.java --template springdoc-v3 --overwrite。
2、CLI自动扫描所有Java Controller文件，识别public @ResponseBody方法，跳过private/protected方法及测试用例。
3、为每个HTTP方法注入完整注解组：@Operation(summary = "根据ID查询用户")、@Parameter(name = "id", required = true, description = "用户唯一标识")、@ApiResponse(responseCode = "200", description = "成功返回用户信息")。
4、对请求体含@RequestBody的方法，自动解析UserDTO.class字段并生成@Schema(allPropertiesRequired = true)嵌套声明。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
