通义灵码怎么生成接口文档_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 流程中就不会出现路径解析失败的问题。