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

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

IDEA 插件市场里搜索 「Apifox Helper」，这是国内一个做 API 协作管理平台的厂商（Apifox）做的插件，可以非常方便自动生成接口文档并且同步到你的项目中。这个插件可以实现代码零入侵自动生产接口文档。

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

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

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

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

（这里强烈推荐同步到 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」就可以同步。

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

这个插件虽然支持导出 markdown，但给别人分享分档的时候不是很方便，有更新的时候也不会同步，需要反复导出。使用 Apifox 项目就可以直接给别人分享一个链接就可以，你之后接口的更新也会直接同步，对方看到的永远是最新的。另外，Apifox 这个产品本身还有很丰富的 API 调试、Mock 、自动化测试等功能，你的前端和测试也可以直接在上面做后续的工作了。这里不细说，有兴趣的可以去找他们官方文档了解。

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

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

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

和 Swagger 有啥不一样？

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

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

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

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

下载链接：apifox.cn