通义灵码接口文档生成操作指南

在开发 Spring Boot 项目时，完成 Controller 方法后，往往还需要补充 Swagger 注释和 Markdown 文档。手动整理接口路径、参数说明、响应结构不仅耗时，还容易遗漏。通义灵码能够自动生成合规的 Swagger 注解、标准 OpenAPI 3 风格文档以及可直接导出的 Markdown 文件，覆盖单方法、整类甚至 CLI 生成 YAML 的全流程。以下介绍具体使用方法。

确认插件启用与账号登录

打开 IntelliJ IDEA，依次点击 File → Settings → Plugins，搜索“Tongyi Lingma”，确保状态为 Enabled。如果尚未安装，点击 Install 后重启 IDE。【未登录阿里云账号会导致所有生成操作返回空或报错】

重启后，右下角会出现“灵码已就绪”提示。点击右侧工具栏的通义灵码图标，选择 Sign in with Alibaba Cloud，扫码完成授权。登录成功后，右上角会显示昵称和在线状态。

为单个接口方法生成 Swagger 注释

将光标放在目标方法（如 @PostMapping 或 @GetMapping）名称正上方的空白行（例如 public ResponseEntity createUser() 上方），按快捷键 Alt+Enter，选择“Generate Swagger documentation”，然后回车确认。

通义灵码会自动解析请求方式、路径、@RequestBody/@RequestParam 参数类型、返回值类型，并生成完整注释块，包含 @Tag、@Operation、@Parameter（自动识别为 path/query/body）、@ApiResponse（200/400/500 基础结构）。如果参数是 DTO，还会递归扫描字段，并注入 @Parameter(description = "用户名") 等描述。

注意：【DTO 类必须已编译通过且在当前 classpath 中可见】，否则字段级注释无法提取，只会标注为 object 类型。

批量为整个 Controller 类生成文档

首先，将光标定位到 @RestController 类声明行的任意位置（例如 public class UserController）。然后，按快捷键 Ctrl+Shift+D（Windows）或 Cmd+Shift+D（Mac）。等待 2～4 秒，系统会自动生成类级 @Tag、每个方法的 @Operation 及参数描述，并统一注入全局错误码响应（401/403/500）。

该模式会跳过已有 Swagger 注释的方法，避免覆盖人工定制内容。右键点击类名，选择 Lingma → Generate Swagger documentation 是等效替代操作。

从 Controller 直接导出 Markdown 接口文档

右键点击 Controller 文件，选择“Generate REST API Documentation”，在弹出的窗口中选择输出路径（推荐填入 docs/api 目录），然后点击 OK。

通义灵码会自动提取所有接口的路径、HTTP 方法、请求头、查询参数、请求体结构（含 DTO 字段注释）、响应示例（基于 @ApiResponse 和实际返回对象），生成标准 Markdown 表格文档。文件默认命名为 user-controller.md，标题自动取自 @Tag 值。

如果方法未编写 Java doc，生成的“接口说明”会为空；如果 DTO 字段缺少 @ApiModelProperty 或 Java doc，参数表格第三列“说明”会显示“无”。这两处需要提前补全并保存文件（Ctrl+S）。

用自然语言指令微调已有注释

在编辑器的任意空白处输入：“给这个 UserController 补全 Swagger 注解，要求所有 POST 接口的请求体参数都带 required = true，错误响应统一标注 400 和 500”，然后按 Ctrl+Enter 提交。

通义灵码不会覆盖重写，而是精准修改已有注释中的 @Parameter(required = true) 和 @ApiResponse(code = 400) 部分。此功能依赖模型版本，需要确保已切换至 Qwen2.5-7B-Instruct 或更高版本。