常见问题

此插件配置过于灵活, 以下均为示例, 需根据实际情况做合适的处理。

如何添加配置文件

参考项目内配置

如何组织 API 到指定模块、API 分组

module 用于分类 api

默认情况下取当前模块名(单模块项目取项目名)

默认推荐配置:

在类上这样注释:

💡

更多详细配置可参考配置文档

怎么设置接口 API 所属文件夹的名称

需要在配置文件里要开启这个配置，以下是 .apifox-helper.properties 示例

# read folder name from tag `folder`
folder.name=#folder

使用 @folder 注释

也可以进行多级目录注释：

💡

更多详细配置可参考配置文档

如何增加外层的公共返回响应 Response 泛型

需要在配置文件里要开启这个配置，以下是 .apifox-helper.properties 示例

# 假定 公共 ResponseDo 的包名为 com.xxx
method.return=groovy: "com.xxx.ResponseDo<" +  it.returnType() +">"

💡

更多详细配置可参考配置文档

如何忽略 API

增加配置:

#ignore class or method which has comment tag 'ignore'
ignore=#ignore

在类上注释@ignore 忽略当前类

在方法上注释@ignore 忽略当前 API

如何设置 API/文件夹的名称/描述

一般来说:

如何在 API/文件夹的描述中说明 API/文件夹被废弃了

默认推荐配置如下:

使用注解或者注释标记 API 废弃即可:

如何在 API 描述中声明 API 需要的权限(javax annotation security)

可考虑增加如下配置:

示例:

如何在 API 描述中声明 API 需要的权限(spring security)

可考虑增加如下配置:

示例:

如何忽略某些字段

使用规则: json.rule.field.ignore

忽略特定名称的字段:

忽略特定类型的字段:

忽略特定限定符的字段:

如何将指定类型转换为另一种类型处理

将java.time.LocalDateTime作为yyyy-mm-dd形式字符串处理

将java.time.LocalDateTime作为timestamp处理

部分接口可能有不同的返回

可以使用 method.doc 将可能的返回放在方法备注中

配置如下:

使用如下:

有的字段可能有不同类型的值

可以使用 field.doc 将可能的类型值放在字段备注中

配置如下:

使用如下:

如何适配 Mybatis Plus 工程的分页 Page 模型和请求参数？

首先确保插件版本升级至 >= 1.1.16，然后可以通过项目内配置规则来实现适配识别。

以下内容里，Page 模型 = com.baomidou.mybatisplus.extension.plugins.pagination.Page，注意有些配置是可选的，根据自己的项目代码风格选择即可。

如果使用了 Page 模型但接口方法的返回值不识别，先确保使用了 method.return 配置，并增加注释 @response 如下图

可选，当一个接口的返回的 Page 模型，导致导出接口信息过多且杂乱无章的问题

可选，当一个接口的返回的 Page 模型作为请求参数，想要忽略一些内置的大部分字段，只保留 current, size

可选，当一个接口的返回的 Page 模型的字段 records 实际想在文档字段改为 data，可以添加下面的配置

参考来源 Github Issue，其他文章

如何开启 javax_validation 分组校验

参照 javax_validation, 在 Preferences(Settings) > Other Settings > EasyApi >Recommend 中移除勾选javax.validation, 勾选javax.validation(grouped)

如何激活对 com.fasterxml.jackson.annotation.JsonIgnoreProperties 的支持

在 Preferences(Settings) > Other Settings > EasyApi >Recommend 中勾选Jackson_JsonIgnoreProperties

导出时出现 com.xxx.Xxx is to complex. Blocked cause by xxx reached xxx, 如何处理

检查错误信息中的类是否不应该出现在请求体/响应中, 可尝试做如下配置:

如果此类确实字段繁多, 需要完全解析, 可通过配置放宽解析限制:

导出时出现 No APIs be found to upload!, 如何处理

检查项目依赖是否成功导入，项目能否成功运行

如何添加配置文件#

如何组织 API 到指定模块、API 分组#

怎么设置接口 API 所属文件夹的名称#

如何增加外层的公共返回响应 Response 泛型#

如何忽略 API#

如何设置 API/文件夹的名称/描述#

如何在 API/文件夹的描述中说明 API/文件夹被废弃了#

如何在 API 描述中声明 API 需要的权限(javax annotation security)#

如何在 API 描述中声明 API 需要的权限(spring security)#

如何忽略某些字段#

如何将指定类型转换为另一种类型处理#

部分接口可能有不同的返回#

有的字段可能有不同类型的值#

如何适配 Mybatis Plus 工程的分页 Page 模型和请求参数？#

如何开启 javax_validation 分组校验#

如何激活对 com.fasterxml.jackson.annotation.JsonIgnoreProperties 的支持#

导出时出现 com.xxx.Xxx is to complex. Blocked cause by xxx reached xxx, 如何处理#

导出时出现 No APIs be found to upload!, 如何处理#

如何添加配置文件

如何组织 API 到指定模块、API 分组

怎么设置接口 API 所属文件夹的名称

如何增加外层的公共返回响应 Response 泛型

如何忽略 API

如何设置 API/文件夹的名称/描述

如何在 API/文件夹的描述中说明 API/文件夹被废弃了

如何在 API 描述中声明 API 需要的权限(javax annotation security)

如何在 API 描述中声明 API 需要的权限(spring security)

如何忽略某些字段

如何将指定类型转换为另一种类型处理

部分接口可能有不同的返回

有的字段可能有不同类型的值

如何适配 Mybatis Plus 工程的分页 Page 模型和请求参数？

如何开启 javax_validation 分组校验

如何激活对 com.fasterxml.jackson.annotation.JsonIgnoreProperties 的支持

导出时出现 com.xxx.Xxx is to complex. Blocked cause by xxx reached xxx, 如何处理

导出时出现 No APIs be found to upload!, 如何处理