通义灵码Swagger接口文档自动生成指南（2025）
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 之上），按下快捷键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 流程中出现路径解析失败。