通义灵码快速生成接口文档与 Swagger 注释
在日常开发中，Controller 接口写完后往往来不及补充 Swagger 注释，而前端同事又急需文档进行联调。通义灵码可以在光标定位后数秒内，基于方法签名、参数类型、返回值和已有 Javadoc，自动生成合规、可直接运行的接口文档，跳过逐行补全的低效环节。下面逐一说明五种生成方式，覆盖从单接口到整类、从注释到 Markdown 文档、从 OpenAPI 文件反向生成等场景。
确认插件已安装并完成阿里云账号登录
首先，打开 IntelliJ IDEA，依次进入 File → Settings → Plugins，搜索 “Tongyi Lingma”，点击 Install，安装完成后重启 IDE。重启后右下角出现「灵码已就绪」提示，表明插件已成功加载。
接着，点击右上角灵码图标，选择 Sign in with Alibaba Cloud，使用扫码授权登录。必须完成登录，否则后续所有生成操作均返回空或报错。
登录成功后，面板右上角会显示用户昵称和在线状态。
为单个接口方法生成 Swagger 注释
将光标定位在目标方法名正上方的空白行（例如 public ResponseEntity 上方），按下快捷键 Alt+Enter → 选择 “Generate Swagger documentation” → 回车确认。
通义灵码将自动解析方法签名、@RequestBody/@RequestParam 注解、参数类型及返回值，并生成包含 @Operation、@Parameter、@ApiResponse 的完整 OpenAPI 3 风格注释块。如果方法包含 DTO 参数，它还会递归扫描字段，自动添加 @Schema 或 @Parameter 描述。
小提示： DTO 类必须已编译通过且在当前项目 classpath 中可见，否则字段类型将被标注为 object。
批量为整个 Controller 类生成文档注释
通义灵码提供了三种触发方式，您可以根据需要任选其一：
- 方法一： 光标置于类名所在行（如
public class UserController）→ 快捷键 Ctrl+Shift+D（Windows）或 Cmd+Shift+D（Mac）→ 等待 2～4 秒。 - 方法二： 右键点击类名 → 选择「AI 生成 Swagger 注解」。
- 方法三： 在编辑器任意空白处输入自然语言指令：“给这个 UserController 补全 Swagger 注解，要求所有 POST 接口的请求体参数都带 required = true，错误响应统一标注 400 和 500”，再按 Ctrl+Enter 提交。
生成标准 Markdown 格式技术文档
第一步：将光标定位在 Controller 类名、方法定义行或整个类的起始大括号处——这是触发上下文感知的关键位置，光标放错会导致生成内容脱离实际结构。
第二步：右键 → 选择「通义灵码」→ 点击「生成技术文档」。
第三步：等待 3～8 秒，右侧弹出预览窗口。文档默认包含「概览」「输入参数」「返回说明」「调用示例」「注意事项」五部分，示例代码自动匹配当前项目使用的 SDK 版本和风格。
第四步：点击预览页右上角「Insert to Editor」按钮，文档将填充至当前编辑器光标所在位置。
从 OpenAPI YAML/JSON 文件生成接口文档
复制 Swagger UI 中导出的 /openapi.json 内容片段（至少包含 paths 和 components），新建一个 openapi.yml 文件粘贴保存 → 右键该文件 → 「通义灵码」→ 「从 OpenAPI 生成技术文档」。
这一步不依赖 Java 源码，但要求 YAML/JSON 文件符合 OpenAPI 3.0 规范，否则字段解析可能中断或缺失。
小提示： 如果想快速验证 OpenAPI 文件是否规范，可先粘贴到 swagger.io 的在线校验工具中检查。
常见问题
- 为什么生成 Swagger 注释后代码报错？ 检查是否已添加
springdoc-openapi或swagger-annotations依赖，通义灵码生成的注解依赖这些库，缺少依赖会导致编译失败。 - 批量生成时部分接口没生成注释怎么办？ 确保光标定位在类名行，而不是方法内部。如果仍然缺失，可单独对缺失方法执行单接口生成。
- 生成的 Markdown 文档能否自定义章节？ 当前版本不支持直接修改模板，但可以在生成后手动编辑左侧预览窗口内容，再点击「Insert to Editor」插入。
通过以上五种方式，无论你是需要快速补全单个接口的 Swagger 注释，还是批量生成整个 Controller 的文档，通义灵码都能在数秒内完成，大幅提升接口文档编写效率。建议根据实际场景选择最合适的方法，例如赶工期时优先使用批量注释，需要对外输出文档时使用 Markdown 生成功能。