写了个插件, 一键自动生成 YApi 接口文档, 适配 IDEA 最新版

做后端最烦的事情之一是什么？

写接口文档。

相信每个 Java 后端开发都经历过这样的场景：花了一整天写完接口，然后对着 Swagger 注解或者 Word 文档吭哧吭哧写文档。更崩溃的是，接口改了，文档忘了更新 —— 等前端同学来问的时候，场面一度十分尴尬。

今天给大家安利一款我自己开发的开源 IntelliJ IDEA 插件 —— YApi Doc Generator，让你彻底告别手动维护 API 文档的痛苦。

为什么会有这个插件？

其实事情是这样的。

之前团队一直用着某款 YApi 插件，虽然功能简单了点，但凑合能用。直到某天我把 IDEA 升级到了最新版，重启之后发现 —— 插件红了，不兼容了。

去 Marketplace 搜了一圈，发现市面上现存的 YApi 插件：

• 有些已经不维护了，最新一次更新还是两三年前，对新版 IDEA 直接报错
• 还在维护的也过于简陋，只支持单服务器单项目，但我们团队同时维护好几个微服务项目，每个对应 YApi 上不同的项目，来回切换配置简直崩溃
• DTO 解析能力基本为零，上传的接口文档只有个 path 和 method，参数和响应全靠手动填

更别提我们的项目用了大量泛型（RestResult<T>、PageVO<T> 等），现有的插件解析出来全是 object，毫无参考价值。

本来想忍忍算了，但每天 CRUD 写完还要去 YApi 网页上一个字段一个字段地填，实在受不了。干脆自己写一个吧。

于是就有了 YApi Doc Generator。

它能做什么？

一句话：在 IDEA 中右键点击你的 Controller 类或方法，插件自动解析代码，直接上传到 YApi 平台生成接口文档。

为什么你需要它？

1. 写文档太慢了

一个简单的 CRUD 接口，写代码 5 分钟，写文档可能要 10 分钟。参数描述、响应结构、字段说明…… 重复劳动毫无技术含量。

2. 文档和代码容易不同步

这是最坑的地方。方法签名改了、字段类型变了、DTO 结构调整了 —— 文档没更新，前端按文档调接口，直接 400/500。

3. YApi 是个好平台，但手动填太麻烦

YApi 本身很好用，可视化编辑、接口 Mock、自动化测试一应俱全。但要在网页上一个个填写接口信息，实在太费劲了。

而这个插件要做的，就是把「IDE 里写代码」到「YApi 上出文档」这最后一公里打通。

核心功能一览

🔍 Controller 智能识别

不管你用 @RestController / @Controller 注解，还是类名以 *Controller 结尾，插件都能自动识别。

📝 全面支持 Spring MVC 注解

🧠 深度 DTO 解析 —— 这是亮点

普通插件可能只解析个字段名和类型就完了，但这个插件能做到：

• 嵌套对象递归解析（最多 10 层）
• 泛型类型替换：RestResult<User> → 自动展开 User 的所有字段
• 集合类型：List、Set、数组都能正确处理
• 枚举智能解析：枚举值自动列出
• 循环引用检测：A 引用 B、B 引用 A？自动终止，不会死循环
• 继承字段收集：父类的字段也会自动包含进来
• @JsonIgnore 字段自动跳过
• JSR-303 验证注解识别（@NotNull、@NotBlank 等）

📤 响应体自动解析

方法的返回值类型也会自动解析为 YApi 的响应结构，请求和响应一步到位。

🏷️ 文档标题智能提取

优先使用 Swagger 注解 @ApiOperation / @Operation 的 value，没有的话自动生成 Controller名称.方法名 格式标题。

📂 分类自动管理

根据 URL 路径的第一段自动创建 YApi 分类，不需要手动在 YApi 页面上建目录。

🔌 多 YApi 服务器支持

• 支持配置多个 YApi 服务器（测试环境、生产环境等）
• 模块名自动匹配：根据模块根目录名自动模糊匹配对应的服务器
• 多个服务器时弹出选择对话框，手动选择

⚡ 快捷键

Ctrl + Alt + Y，选中目标直接生成，效率拉满。

3 分钟快速上手

第一步：安装插件

打开 IntelliJ IDEA → File → Settings → Plugins → 搜索 YApi Doc Generator → 安装。

或者从 GitHub Releases 下载后手动安装。

第二步：配置 YApi 服务器

File → Settings → Tools → YApi Doc Generator，点击 + 号添加：

• 服务器名称：给服务器起个名字（如"测试环境"）
• 服务器地址：YApi 服务地址
• Token：YApi 项目设置中获取
• 项目 ID：YApi 项目 ID

第三步：一键生成

在 Controller 类名或方法上右键 → Generate YApi Doc，搞定。

适用人群

• 使用 Spring Boot / Spring MVC 的 Java 后端开发者
• 团队使用 YApi 管理接口文档
• 厌倦了手动写文档、想提升开发效率的人

技术栈

• 基于 IntelliJ Platform 2024.3 开发
• 兼容 IntelliJ IDEA 2023.2+（含 Community 和 Ultimate）
• 使用 Java HttpClient 调用 YApi 开放 API
• 开源免费，Apache 2.0 协议

写在最后

这个插件本身不算复杂，但对于日常使用 YApi 的团队来说，确实能省下不少时间。代码完全开源在 GitHub 上，欢迎 Star、提 Issue 或贡献代码。

GitHub 地址：https://github.com/socbb/idea-plugin-yapi

如果你也在为接口文档发愁，不妨试试看，也许这就是你要找的工具。

如果觉得有用，欢迎分享给身边的同事和朋友 🤝