接口文档的维护，历来是开发团队的一块心病——代码改了一行，文档就得跟着更新，稍不留神就会出现“代码跑通了，文档却还停在两个月前”的尴尬局面。百度 Comate 给出的解决方案很有意思：直接从 Java Controller 代码中提取结构化信息，自动生成可读性强的接口文档，彻底省去了手动同步的繁琐过程。

当然，想要快速获得准确、格式美观的结果，还是有几个关键前提需要注意的。下面从三种常见场景出发，看看 Comate 具体如何高效使用。

用Comate直接解析Java Controller生成接口文档

操作前提很简单：你正在编辑一个 Spring Boot 项目中的 Controller 类，比如 UserController.java，并且这个类已经正确标注了 @RestController、@RequestMapping 等注解。

具体怎么做？选中整个 Controller 类的代码，右键选择「Baidu Comate」→「生成接口文档」。这一步触发的背后，Comate 会对当前类进行完整的语义分析：它会自动识别出接口路径、HTTP 方法、请求参数的类型（@PathVariable、@RequestParam、@RequestBody），以及响应实体的结构。如果 Controller 中使用了 Lombok 的 @Data 或 @Builder，Comate 也能自动展开字段——但这里有一个硬性条件：返回类型必须是明确的 POJO 类，不能是 Map 或 Object，否则生成的字段列表将会一片空白。

生成的结果是 Markdown 格式，内容包含接口地址、请求方式、请求头示例、入参表格（标注了是否必填、类型、说明），以及响应体的 JSON 结构树。可以直接复制粘贴到 Confluence 或语雀发布，非常省时省力。

基于已有API文档知识集批量生成调用代码+文档

如果手中已经有现成的 API 描述文件——比如 Swagger JSON、OpenAPI YAML，或者从 Postman 导出的 JSON——Comate 可以将它作为“知识集”导入，之后所有提问都会以这份知识作为依据。

导入方式有两种：

第一种：在 IDE 右下角点击 Comate 图标 →「知识中心」→「+新增知识集」，为知识集命名（例如“订单服务v3”），然后上传本地的 openapi.json 文件。

第二种：打开任意代码文件，激活 Comate 对话框，输入 # 符号 → 选择「知识集」→「上传新知识集」，直接拖入 YAML 文件，等待 3～8 秒解析完成即可。

上传成功后，在同一个对话框里输入类似指令：“根据知识集‘订单服务v3’，生成 Java 调用 /cancelOrder 接口的完整代码，包含异常处理和超时配置”。Comate 会输出带注释的 RestTemplate 或 WebClient 调用片段，并附带该接口的精简说明卡片——包含路径、必需 Header、入参约束和典型返回码，相当于文档和代码一次性提供到位。

给单个接口加注释后一键补全文档字段

前面两种方法面向批量场景，如果只想快速为某个接口补充文档字段，还有更轻量的操作。

第一步：在 Controller 方法上方空白处输入 /** 并回车，触发 IDE 自带的注释模板。

第二步：在生成的 Javadoc 里写一句中文描述，比如“取消指定用户订单，支持软删除与异步通知”。

第三步：将光标停在注释末尾，按快捷键 Alt+Enter（Windows）或 Option+Enter（macOS），选择「Comate：增强此注释」。Comate 会自动补全 @ApiOperation、@ApiParam、@ApiResponse 等 Swagger 注解，同时右侧预览面板中也会同步显示填充后的效果。如果想导出为独立文档，点击面板底部的「导出为 Markdown」，就能得到仅针对该接口的页面，其中还包含了请求示例的 curl 命令和响应样例。

不过需要注意，这个增强功能的前提是项目已经引入了 springfox-swagger2 或 springdoc-openapi 依赖，否则生成的注解无法被 Swagger UI 识别，相当于做了无用功。