Apifox IDEA 插件快速上手
Apifox Helper 是 Apifox 团队针对 IntelliJ IDEA 环境所推出的插件，可以在 IDEA 环境中识别本地 Java、Kotlin 后端项目的源代码，自动生成 API 文档并一键同步到 Apifox 的项目中。
对于常见的开发框架，Apifox Helper 插件能够做到开箱即用，实现真正的代码零侵入。如下图所示，仅通过识别最基本的 SpringBoot 代码，即可生成一份详尽的 API 文档：
支持开箱即用的框架和库如下：
| 类型 | 名称 | 注解示例 |
|---|---|---|
| 服务端框架 | • Spring • Jakarta RESTful Web Services (JAX-RS) | @RestController, @GetMapping @Path, @Get |
| 校验库 | • Jakarta Bean Validation • Java Bean Validation | @NotNull |
| 序列化库 | • FASTJSON • Jackson • GSON | @JsonProperty @SerializedName |
| API 规格库 | • Swagger 2.x • Swagger/OpenAPI 3.x | @ApiOperation, @ApiParam |
| 客户端库 | • Spring Cloud OpenFeign | |
| 性能指标库 | • Spring Boot Actuator | |
| 语言与注释 | • Java: Javadoc • Kotlin: KDoc |
本插件基于 easy-api 定制开发，感谢 easy-api 作者。
1. 安装
在 IntelliJ IDEA 的插件 Marketplace 内搜索 Apifox Helper 进行安装。
插件支持 IntelliJ IDEA 2019.3 及更高的版本。
2. 配置 API 访问令牌
在使用 Apifox Helper 插件之前，需要提前注册 Apifox 账号，并生成对应的 API 访问令牌，详细说明请参考《Apifox 开放 API》。
在 Apifox Helper 内填写自己的 API 访问令牌，然后点击「测试令牌」。如果测试成功，请点击「应用」或「确定」按钮，然后正常使用 Apifox Helper。
3. 同步接口
支持同步以下范围内的接口：
- 模块内的全部接口：在左侧目录树的模块节点，点击右键，选择「Upload to Apifox」
- Controller 内的全部接口：在 Controller 文件内部，点击右键，选择「Upload to Apifox」
如果是首次同步，需要在弹出的对话框内选择接口的目标同步项目，你可以选择项目或项目内的目录。如果选择项目，则将会上传至项目的根目录。
数据模型无需配置，API 文档将默认上传至接口所在项目的数据模型根目录。
Apifox Helper 旧版本中所提供的，通过输入文字来指定上传的目标目录方式将被废弃。如果你使用该方式指定目录，当项目内的其他目录存在相同接口时，有可能出现以下问题：
- 创建了新的目录，但是目录内没有接口，即产生空目录；
- 创建了新的目录，目录内有接口，但是其他目录内的同名接口消失。
请尽快改用新的目录选择方式。
4. 查看接口文档
API 文档同步成功后，打开 Apifox。点击右上角的刷新按钮，即可看到从 Java 或 Kotlin 源代码中识别出来的接口文档。
你可以非常方便的将自动生成的 API 文档分享出去，以便其他人可以很方便地通过浏览器中进行查看。详细说明请参考《在线分享》。
常见问题
- 为什么给数据模型（DTO）的某个字段添加了 @NotNull 注解，生成的接口文档却没有显示「必填」或「不可为空」？
@NotNull 注解属于 jakarta.validation.constraints 或 javax.validation.constraints 库。请在「远程配置」中勾选对应的配置文件，然后重新同步接口。
- 为什么代码中使用了 Swagger 的注解，生成的接口文档却没有体现？
请在「远程配置」中勾选 Swagger 或者 Swagger 3 的配置文件，然后重新同步接口。
- 为什么 IDEA 控制台输出的中文，比如项目名称，无法正常显示？
请在「更多设置项」中调整 Common 的 charset 设置，依次尝试里面的不同编码。
- 为什么上传时控制台会报错：
exception: kotlin.Unit？
如果全新安装了 1.2.3 版本，首次上传接口时会弹窗问是否信任 https://api.apifox.com，如果选择了否，则会出现本错误。
请在插件的「更多设置项」，检查 Trust Hosts 内的 Apifox 官方域名前是否有感叹号。如果有，请删除感叹号并保存。
隐私与安全声明
Apifox Helper 插件仅在用户本机执行对于 Java 、Kotlin 源代码的识别工作。Apifox 重视您的数据资产安全，您的 Java 、Kotlin 源代码永远不会被上传至 Apifox 服务器。
联系我们
在使用 Apifox Helper 插件中所遇到的任何问题或建议反馈，请添加下方微信（备注：IDEA），加入用户群沟通交流。
