通义灵码Swagger接口文档自动生成方法

在 Spring Boot 项目开发中，Controller 层往往已经写好，但 Swagger 注解还没来得及补充。手动添加 @Api、@ApiOperation、@ApiParam 这些标记，不仅耗时，还容易遗漏字段或写错类型——这类重复性工作，不值得投入太多精力。

通义灵码可以有效解决这个问题。将光标定位后，几秒钟内就能自动生成完整、合规、可直接运行的 Swagger 文档注释。下面介绍具体用法。

在 IntelliJ IDEA 中启用通义灵码

首先安装插件。打开 Settings → Plugins → 搜索 "Tongyi Lingma" → 点击 Install → 重启 IDE。重启后右下角会出现 「灵码已就绪」 的提示，说明插件已加载成功。

首次使用需要登录阿里云账号：点击右上角灵码图标 → Sign in with Alibaba Cloud → 扫码授权。这一步不可跳过——未登录状态下，所有生成能力都会被禁用。

【必须完成登录，否则后续所有生成操作均返回空或报错】

为单个 Controller 方法生成 Swagger 注释

这是最常用、最直接的场景。将光标放在目标方法名正上方的空白行（例如 public ResponseEntity createUser(...) 的上方），按快捷键 Alt+Enter → 选择 "Generate Swagger documentation" → 回车确认。

通义灵码会自动解析方法签名、参数类型、返回值，以及 @RequestBody / @RequestParam 等注解，生成带有 @Api、@ApiOperation、@ApiResponses 的完整注释块。生成的内容严格遵循 Swagger 2.0 规范，200/400/500 状态码的响应体标注都会包含在内。

如果方法中使用了 DTO 参数，它还会递归扫描 DTO 类的字段，自动添加 @ApiModelProperty(value = "用户名", required = true) 这类注解，省去了手动跳转到 DTO 类里逐个添加的麻烦。

批量为整个 Controller 类生成文档注释

需要为整个类生成文档时，有两个入口可供选择。

方法一：光标放在类名所在行 → 快捷键 Alt+Enter → 选择 "Generate Swagger documentation for class"。

方法二：右键点击类名 → Lingma → Generate Swagger documentation。

生成的成果包括类级别的 @Api 注解（例如 value = "用户管理接口"）、每个方法的 @ApiOperation 及参数描述，还会统一注入 @ApiResponses 全局错误码说明（如 401 Unauthorized、403 Forbidden 等）。值得留意的是，该模式会跳过已经存在 Swagger 注释的方法，避免覆盖之前手动调整过的内容。

从 Controller 直接导出 Markdown 接口文档

有时前端同事催得急，需要一份干净的接口文档。无需启动 Swagger UI，直接在 Controller 文件上操作即可。

第一步：右键点击 Controller 文件 → 选择 "Lingma → Export as Markdown API doc"。

第二步：在弹出的窗口里勾选 "Include request/response examples" → 点击 Export。

第三步：指定保存路径。生成的 user-controller-api.md 文件采用标准三级标题结构——接口名称、请求方式、路径、参数表格、响应示例、curl 调用示例一应俱全。所有字段类型与实际代码完全一致，连泛型嵌套（例如 List）也能准确还原。不依赖本地 Swagger UI 启动，导出即用，可直接发给前端或插入 Confluence。

生成 Swagger YAML 文件供 CI/CD 使用

如需将文档集成到 CI/CD 流程中，可以通过命令行方式生成 YAML。打开 Terminal，进入项目根目录，执行命令：lingma swagger export --controller com.example.api.UserController --output openapi.yaml。

该命令会调用通义灵码 CLI 工具，基于当前代码状态实时解析，输出符合 OpenAPI 3.0.3 规范的 YAML 文件。生成的文件包含 servers、components/schemas、paths 的全量结构，可直接导入 Swagger Editor 或 API 网关的 OpenAPI 导入功能。

值得说明的是，YAML 中的 $ref 引用全部展开为内联定义，不依赖外部文件，这样在 CI 流程中不会出现路径解析失败的问题。