如何自动生成 API 接口文档 - 一份详细指南

比眉伴天荒 2023-10-09 19:48 8阅读 0赞

1.  **自动生成接口文档：** 不用手写，一键点击就可以自动生成文档，当有更新时，点击一下就可以自动同步接口文档；
2.  **代码零入侵：** 完美解决了使用 Swagger 在我们的代码中额外增加各种注解，导致代码可读性极差、入侵了逻辑代码的问题；
3.  **团队合作更方便：** 不需要导出文件，云端管理，直接分享链接给团队即可；
4.  **生成的文档好看！** （如下图）

![format_png][]

### 第一步：安装 Apifox IDEA 插件（Apifox Helper） ###

打开你的 IDEA，点击 File -->Settings --> Plugins,搜索 **Apifox Helper。** 点击安装。

![format_png 1][]

### 第二步：配置 Apifox 访问令牌 和项目 ID ###

（这一步假设你已经注册过 Apifox，且已经创建了项目。如果没有，请[去注册][Link 1] 并且创建一个项目用来同步你的接口文档。）

接下来，你需要将 Apifox Helper 和 Apifox 的项目进行关联，也就是通过访问令牌绑定。

1、打开 Apifox， 点击左侧【头像】-->【账号设置】-->【API 访问令牌】-->【新建令牌】,填写令牌名称，点击【保存并生成令牌\]】，复制令牌；

![format_png 2][]

2、在 Apifox 中进入项目，【项目设置 --> 基本设置】，复制项目 ID 。

![format_png 3][]

在 IDEA 中，点击 File-->Settings -->Other Settings，找到 **Apifox Helper。** **将刚才复制的访问令牌和项目 ID 粘贴到这里：**

3、（服务器地址就用默认的，可以不用管。）

![format_png 4][]

到这里，你就搞定了配置部分，下面就是自动生成文档了！

### 第三步：自动生成文档！ ###

在 IDEA 中右键点击「 Upload to Apifox」，就可以生成 API 接口文档了！Upload to Apifox 可以生成单个接口，也能一键把 Controller 里面的所有接口全部生成！甚至把整个项目上右键一起生成接口文档。

![format_png 5][]

### 第四步：去 Apifox 项目中查看自动生成的文档 ###

点击 Apifox 右上角的刷新图标。刚才在 IDEA 项目中的接口文档就已经在这里了。

![format_png 6][]

这样，你就大功告成了！恭喜你已经拥有了一份美观整洁的接口文档。这个项目一旦有更新，你只需要右键点击「 Upload to Apifox」 就可以。另外还可以通过阅读[ Apifox 插件官方帮助文档][Apifox] ，帮助你解决更多特定业务情景的插件使用问题。

### Apifox 更多好用的功能 ###

#### 在线分享接口文档 ####

当你的文档同步到项目中，那么你就可以直接在 Apifox 中直接生成一个分享链接给别人，那么他看到的文档就都是最新的，不需要再管你索要接口文档文件。

![format_png 7][]

#### 调试方便 ####

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

![format_png 8][]

#### 云端 Mock ####

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

![format_png 9][]

#### 接口自动化测试能力 ####

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

![format_png 10][]

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

![format_png 11][]

### 了解更多自动生成文档的方法。 ###

作者：切克呦  
链接：https://juejin.cn/post/7225534193995153464

[format_png]: https://img-blog.csdnimg.cn/img_convert/319bba7462241f816a8afdb7522c7c8a.webp?x-oss-process=image/format,png
[format_png 1]: https://img-blog.csdnimg.cn/img_convert/d21430dd243db5041aa156bfe504d957.webp?x-oss-process=image/format,png
[Link 1]: https://link.juejin.cn?target=https%3A%2F%2Fapifox.com%2F
[format_png 2]: https://img-blog.csdnimg.cn/img_convert/d5d91b14d33f34c6343b19534d5ffaac.webp?x-oss-process=image/format,png
[format_png 3]: https://img-blog.csdnimg.cn/img_convert/7c609c2c45763142e89f5ce1af6a101a.webp?x-oss-process=image/format,png
[format_png 4]: https://img-blog.csdnimg.cn/img_convert/8b35c1e7f98f810ce43531ab0a294843.webp?x-oss-process=image/format,png
[format_png 5]: https://img-blog.csdnimg.cn/img_convert/263b3d09ec063b5bff65583775d8ce80.webp?x-oss-process=image/format,png
[format_png 6]: https://img-blog.csdnimg.cn/img_convert/c6b0be73c43c4b07d92fb7a32941cb34.webp?x-oss-process=image/format,png
[Apifox]: https://link.juejin.cn?target=https%3A%2F%2Fwww.apifox.cn%2Fhelp%2Fide-plugin%2Fidea-plugin%2Fquickstart%2Fintroduction%2F
[format_png 7]: https://img-blog.csdnimg.cn/img_convert/a7ac15d4decc4f24b76273bbfea5d438.webp?x-oss-process=image/format,png
[format_png 8]: https://img-blog.csdnimg.cn/img_convert/f2286cea16b902b752a589d5cf731a55.webp?x-oss-process=image/format,png
[format_png 9]: https://img-blog.csdnimg.cn/img_convert/4e53217485f8ffe4e4e04ca2a794b5a0.webp?x-oss-process=image/format,png
[format_png 10]: https://img-blog.csdnimg.cn/img_convert/8e44d8ae8c469b22af768c1b47b2913a.webp?x-oss-process=image/format,png
[format_png 11]: https://img-blog.csdnimg.cn/img_convert/95a1d653b496e1aa4d0257261d7d6632.webp?x-oss-process=image/format,png