跳到主要内容

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 文档分享出去,以便其他人可以很方便地通过浏览器中进行查看。详细说明请参考《在线分享》

常见问题

  1. 为什么给数据模型(DTO)的某个字段添加了 @NotNull 注解,生成的接口文档却没有显示「必填」或「不可为空」?

@NotNull 注解属于 jakarta.validation.constraintsjavax.validation.constraints 库。请在「远程配置」中勾选对应的配置文件,然后重新同步接口。

  1. 为什么代码中使用了 Swagger 的注解,生成的接口文档却没有体现?

请在「远程配置」中勾选 Swagger 或者 Swagger 3 的配置文件,然后重新同步接口。

  1. 为什么 IDEA 控制台输出的中文,比如项目名称,无法正常显示?

请在「更多设置项」中调整 Common 的 charset 设置,依次尝试里面的不同编码。

隐私与安全声明

Apifox Helper 插件仅在用户本机执行对于 Java 、Kotlin 源代码的识别工作。Apifox 重视您的数据资产安全,您的 Java 、Kotlin 源代码永远不会被上传至 Apifox 服务器。

联系我们

在使用 Apifox Helper 插件中所遇到的任何问题或建议反馈,请添加下方微信(备注:IDEA),加入用户群沟通交流。