超简单！Java 项目自动生成接口文档教程

Posted 2023-04-28 tcsztzf

你还在用 word、markdown 埋头苦干写接口文档？写文档这件事恐怕是每个开发都万分抗拒的事情了。本篇文章详细教你如何利用插件工具，在 IDEA 中自动生成 API 文档。

先来看看从 IDEA 中生成文档的效果如下图。下图是使用 Apifox 插件（Apifox helper）从 IDEA 生成的文档（右）效果。

第一步：安装插件

打开你的 IDEA，点击 File —>Settings —> Plugins,输入 Apifox Helper。 点击安装，然后等待成功后重启 IDEA.

你也可以通过 Jetbrains Marketplace 的官网下载安装。

第二步：注册一个 Apifox 账号

Apifox 是一个在线的接口文档管理工具，这一步主要是用来同步文档到项目中。支持下载桌面端或直接网页注册，并且创建一个项目。

第三步：配置令牌

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

1、打开 Apifox， 点击左侧【头像】—>【账号设置】—>【API 访问令牌】；

2、点击【新建令牌】，填写令牌名称，点击【保存并生成令牌】。

3、复制令牌到 IDEA 中【Apifox Helper】配置项的 API 访问令牌中。同理，在 Apifox 中进入项目，【项目设置 —> 基本设置】，复制项目 ID 。

4、在 IDEA 中，点击 File—>Settings —>Other Settings，找到 Apifox Helper。 将访问令牌和项目 ID 粘贴到这里：

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

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

第四步：生成文档！

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

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

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

自此，你就大功告成了！恭喜你已经拥有了一份美观整洁的接口文档。这个项目一旦有更新，你只需要右键点击「 Upload to Apifox」 就可以。

更多好用的功能

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

还可以直接在 Apifox 项目中直接发起接口调试、接口自动化测试等等操作。相较于 Postman，Apifox 结合它的插件 Apifox Helper 可以通过代码注解自动解析生成 API 文档，无需手动操作，同时支持远端同步，非常方便团队内的协作和更新。这是一种新型的在线协作方式，能够非常高效率帮助你进行 API 接口的分享和管理。懒人必备！ 另附带 Apifox 插件官方帮助文档 ，帮助你使用。

Spring Boot - 自动生成接口文档

参考技术A

在目前主流的前后端分离项目中，桥接前后端的就是接口，因此，一份简洁易懂的接口文档就显得非常重要了。幸运的是，我们不必手动去编写这些接口文档，市面上已有许多成熟的第三方库可以自动为项目生成接口文档，在 Spring Boot 中，最常使用的接口文档自动生成库就是 Swagger。

本篇博文主要介绍在 Spring Boot 中集成 Swagger 3 的方法。

更多详细信息，请参考官网： Specification

简单来说， OpenAPI 就是定义描述 REST API 的规范，而 Swagger 就是对 OpenAPI 规范的实现。

在 Spring Boot 中集成 Swagger 3，步骤如下：

可以看到，Swagger 3 的使用还是非常简单的。

如果需要更细致的自定义配置，我们可以自定义一个配置类，然后注入一个 Docket 数据实例，自定义配置 Swagger。

以下列举几种常见的配置示例：

Swagger 更多配置选项，请参考官方文档： springfox

Swagger 在使用过程中，有一些事项可以注意一下，避免出现问题。比如：