分享IDEA通过插件【一键自动生成】在线api接口文档

深碍√TFBOYSˉ_ 2023-09-27 14:35 127阅读 0赞

开发写代码已经很辛苦，相信每个开发人员都不想写接口文档，但是不写又不行。尤其现在开发的项目偏向于前后端分离，在没有接口的情况下，前后端很难对接联调，测试也无法很好的测试。现在IDEA的插件仓库里有款插件：**Apifox Helper**，可以解放双手，自动生成接口文档了。（本人用的IDEA版本是2022.2）

#### 一、安装 ####

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

![8ccdf8f4309f4ea29f3da63095e8efa2.jpeg][]

我这里是已经下载过了的。

如果下载插件速度慢，也可以去 Jetbrains Marketplace 的官网下载(**PS：根据你本地的IDEA版本下载对应的插件，千万不要下错了**)：[Jetbrains Marketplace官网][Jetbrains Marketplace]

![b2e4a46460d5406abb5fb39079f8d32d.jpeg][]

![376c4768ff2247bfa67c466978c151f4.jpeg][]

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

**PS：强烈推荐同步到 Apifox 项目（原因后面会说到）**

*  注册/下载地址：[Apifox官网][Apifox] ；直接用微信扫一扫注册就行，非常便捷
 *  创建项目：登录apifox > 创建团队 > 新建项目，填入对应的项目名称

![decf1aceb1324137936cdfcc9b491371.jpeg][]

#### 二、IDEA项目与Apifox项目关联 ####

插件安装后，需要将 IDEA 内的项目与 Apifox 的项目进行关联，需要相关的配置，如下：

![6f14c50053074a3cb254aa44dfc8cdf8.jpeg][]

1.  **Apifox 服务器地址：**默认的服务地址为 https://api.apifox.cn，直接用默认地址，不需要修改。
2.  **填写 Api 访问令牌：**在 Apifox 个人头像处的**账号设置**中选择**API 访问令牌**，新建令牌后复制生成的 Token 填写到以上插件设置中。![28574dccc41943279059158f94de6694.jpeg][]![1e2e09f6b9034a9d86dd10cdccfd6430.jpeg][]
3.  **模块项目 ID 配置：** 这项主要是进行代码模块名和项目 ID 的映射关系配置。在 Apifox 中对应项目的**项目设置**中选择**基本设置**，复制并保存项目 ID，填写在以上的对应模块名处。

![484c51eea74142279dfa8f42fef2efeb.jpeg][]

![2fdd4d4c15134981a2e344982c68988f.jpeg][]

到这里，就完成全部的设置了，可以实现文档的自动生成和更新同步了。

**PS：**每个项目只需要开始的时候设置这一次，后面就不需要做这个操作了。

#### 三、自动生成接口文档 ####

**PS：记得在Controller类上要加入@Api注解**

**![1c8f2b009c5145029129a4e816fcac9e.jpeg][]**

1.打开需要上传的 Controller 类，右键选择 **Upload to Apifox**

![076cee10be2b4f9b86fcc4a6c2693b29.jpeg][]

2.打开 Apifox 创建的项目，就可以看到刚才自动同步过来的文档了 ![54c0da7e5dac466d9946888852681614.jpeg][]

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

#### 四、为什么强烈推荐同步到 Apifox 项目 ####

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

![86769cc4ee6c4a09a4177facc16c72b4.jpeg][]

![4103f127c89847e5afecae6284f7cc21.jpeg][]

#### 五、Apifox 与 Swagger区别 ####

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

*  Swagger：需要写注释，对逻辑代码有入侵，功能单一，不利于前后端对接联调；
 *  Apifox：可以基本实现代码零入侵，使用标准的 Javadoc 注释就可以自动生成。同时它也支持同步 Swagger 的文档到项目里。还有 API Mock、自动化测试等延伸功能。

#### **如果这篇文章对您有所帮助，或者有所启发的话，求一键三连：点赞、评论、收藏➕关注，您的支持是我坚持写作最大的动力。** ####

[8ccdf8f4309f4ea29f3da63095e8efa2.jpeg]: https://img-blog.csdnimg.cn/8ccdf8f4309f4ea29f3da63095e8efa2.jpeg
[Jetbrains Marketplace]: https://plugins.jetbrains.com/
[b2e4a46460d5406abb5fb39079f8d32d.jpeg]: https://img-blog.csdnimg.cn/b2e4a46460d5406abb5fb39079f8d32d.jpeg
[376c4768ff2247bfa67c466978c151f4.jpeg]: https://img-blog.csdnimg.cn/376c4768ff2247bfa67c466978c151f4.jpeg
[Apifox]: https://www.apifox.cn/
[decf1aceb1324137936cdfcc9b491371.jpeg]: https://img-blog.csdnimg.cn/decf1aceb1324137936cdfcc9b491371.jpeg
[6f14c50053074a3cb254aa44dfc8cdf8.jpeg]: https://img-blog.csdnimg.cn/6f14c50053074a3cb254aa44dfc8cdf8.jpeg
[28574dccc41943279059158f94de6694.jpeg]: https://img-blog.csdnimg.cn/28574dccc41943279059158f94de6694.jpeg
[1e2e09f6b9034a9d86dd10cdccfd6430.jpeg]: https://img-blog.csdnimg.cn/1e2e09f6b9034a9d86dd10cdccfd6430.jpeg
[484c51eea74142279dfa8f42fef2efeb.jpeg]: https://img-blog.csdnimg.cn/484c51eea74142279dfa8f42fef2efeb.jpeg
[2fdd4d4c15134981a2e344982c68988f.jpeg]: https://img-blog.csdnimg.cn/2fdd4d4c15134981a2e344982c68988f.jpeg
[1c8f2b009c5145029129a4e816fcac9e.jpeg]: https://img-blog.csdnimg.cn/1c8f2b009c5145029129a4e816fcac9e.jpeg
[076cee10be2b4f9b86fcc4a6c2693b29.jpeg]: https://img-blog.csdnimg.cn/076cee10be2b4f9b86fcc4a6c2693b29.jpeg
[54c0da7e5dac466d9946888852681614.jpeg]: https://img-blog.csdnimg.cn/54c0da7e5dac466d9946888852681614.jpeg
[86769cc4ee6c4a09a4177facc16c72b4.jpeg]: https://img-blog.csdnimg.cn/86769cc4ee6c4a09a4177facc16c72b4.jpeg
[4103f127c89847e5afecae6284f7cc21.jpeg]: https://img-blog.csdnimg.cn/4103f127c89847e5afecae6284f7cc21.jpeg