IDEA 版 API 接口神器来了，一键生成文档，贼香！

前言

每个开发都不想写文档。当你不想写接口文档时，可以通过安装插件在 IDEA 里实现自动同步，一边写代码一边同步接口文档给你的前端、测试同学。以下内容手把手教你怎么操作（这里仅面向使用 IDEA 编辑器、遵循 Java Spring 框架注释规范的同学）

目录

前言

首先，你需要安装一个插件

第二步，把你 IDEA 中的项目和 Apifox 的项目关联

第三步，自动生成接口文档

有了这个插件，你还可以直接在 IDEA 里调试

和 Swagger 有啥不一样？

为什么推荐创建一个 Apifox 项目？

调试方便

云端 Mock

文档页面的布局设计能力

自动化测试能力

---

首先，你需要安装一个插件

IDEA 插件市场里搜索 Apifox Helper ，这是 Apifox 团队做的插件，可以非常方便自动生成接口文档并且同步到你的项目中。这个插件可以实现代码零入侵自动生产接口文档。

• IDEA 安装插件：打开 IDEA > Preferences(Settings) > Plugins，搜索 Apifox Helper，点击安装。这里如果存在安装速度慢，你也可以去 Jetbrains Marketplace 的官网下载。

安装完成后，你可以选择同步到 Apifox 项目中，也可以直接导出 Markdown 文档。如果是同步到 Apifox 项目，你还需要下载或注册 Apifox 软件，创建一个对应的项目：

• 注册/下载地址： http://apifox.cn/b3guide1 ，直接微信扫一扫就可以，非常简单。

• 创建项目：点击创建团队 >新建项目，填入对应的项目名称。

（这里强烈推荐同步到 Apifox 项目，原因后面说）

第二步，把你 IDEA 中的项目和 Apifox 的项目关联

插件安装成功后，要将 IDEA 内的项目与 Apifox 的项目进行相关联，需要配置令牌。在 IDEA 中进入插件设置界面 Preferences(Settings) > Apifox Helper 中填写即可。需要填写的基础信息有三个：

1、 Apifox 服务器地址： 默认 Apifox API 服务地址为 https://api.apifox.cn ，默认就填好了，不需要修改。

2、 填写 Apifox 个人访问令牌： 在 Apifox 个人头像处的【账号设置】中选择【API 访问令牌】，新建令牌后复制生成的 Token 填写到以上插件设置中。

3、 模块项目 ID 配置： 这项主要是进行代码模块名和项目 ID 的映射关系配置，在 Apifox 中对应项目的【项目设置】中选择【基本设置】，复制并保存项目 ID，填写在以上的对应模块名处。

到这里，就完成全部的设置动作，可以实现文档的自动生成和更新同步了。说明一下：每个项目只需要开始的时候设置这一次，后面就不需要做这个操作了。

第三步，自动生成接口文档

1、打开需要上传的 Controller 文件，右键选择「 Upload to Apifox」。

2、去 Apifox 项目内，就可以看到刚才自动同步过来的文档了。

3、当后续接口代码有变动或更新时，再次点击「 Upload to Apifox」就可以同步。

有了这个插件，你还可以直接在 IDEA 里调试

Apifox Helper 支持在 IDEA 中一键发起接口自测，不需要切换其他软件。在 IDEA 中选中需要调试的 API 文件，右键选择「Call API」发起请求就可以。

当然，以上只是简单版本的自动同步文档，没有什么特殊情况也就可以满足使用了。当然，可能会存在一些特殊的要求，比如说，设置接口 API 所在的文件夹名称、想要忽略某些 API 不同步等等情况。在他们的官方文档上是推荐使用配置文件的方式实现你各种特殊规则和要求的。详情可以自行去 Apifox 官方查阅。

和 Swagger 有啥不一样？

很多开发都习惯用 Swagger，用 Swagger 可以一定程度上解决自动生成文档的问题，但有一个很大的缺点：你需要写大量的注解，会对你的逻辑代码有入侵。并且在功能的全面性上不如 Apifox 。

• Swagger：需要写注解，对逻辑代码有入侵，功能单一；

• Apifox：使用标准的 Javadoc 注释，基本可以实现代码零入侵。同时它也支持同步 Swagger 的文档到项目里。还有 API Mock、自动化测试等延伸功能。

推荐用法是可以省略 Swagger 这一步，直接安装这个插件使用就可以。

为什么推荐创建一个 Apifox 项目？

这个插件虽然支持导出 Markdown，但给别人分享分档的时候不是很方便，有更新的时候也不会同步，需要反复导出。使用 Apifox 项目就可以直接给别人分享一个链接就可以，你之后接口的更新也会直接同步，对方看到的永远是最新的。

另外，Apifox 这个产品本身还有很丰富的 API 调试、Mock 、自动化测试等功能，你的前端和测试也可以直接在上面做后续的工作。

调试方便

当你通过插件同步了文档到 Apifox 项目里后，前端同学直接在文档内就可以一键点击「运行」调试，不需要再复制粘贴、也不需要和后端开发反复核对参数等信息。

云端 Mock

Apifox 内置强大的 Mock 能力，可以直接生成非常智能、人性化的 Mock 数据。把接口文档中的 Mock 功能打开，复制链接到浏览器中回车一下，就能得到 Mock 数据。前端在后端的接口出来之前就可以通过 Mock 功能来制造假数据接口来进行开发和调试。

文档页面的布局设计能力

支持对文档界面的导航和样式做设计，比如导航做成符合产品的下拉菜单、注册登录按钮等，和产品网站融合度更高。

自动化测试能力

测试同学也可以在 Apifox 对接口进行测试。每个接口文档可以快速生成多个不同状态（成功、失败）的测试用例。

对测试步骤进行编排，模拟业务情景设置测试流程控制条件（循环、判断、等待）：

Apifox 的产品体验比较好，适合团队各个角色一起在里面协作，也不需要再使用 postman、swagger 多个工具切来切去了。有兴趣的同学可以前往 Apifox 官网体验、看使用文档。