Apifox IDEA 插件使用指南 - 从入门到精通（3）

引言

在上一篇文章中，我们探讨了Apifox Helper插件的冲突处理与文档风格，相信大家对它的功能已经有了初步了解。今天，我们将聚焦于一个更为核心的主题------内置规则。

作为Apifox Helper插件的基石，内部规则的重要性不言而喻。它不仅决定了插件的运行逻辑，还直接影响其效率和稳定性。正因如此，我决定用一整篇文章来深入剖析这一关键模块，帮助大家更好地理解其设计原理与应用场景。

如何找到内置规则？

点击菜单栏中的 "Setting"（设置）。
在设置页面中，找到并选择 "代码识别" 选项。
在代码识别页面，即可看到 "内置规则" 模块。

接下来，我将从 Apifox Helper 插件为我们划分的多个维度，逐一展开详细介绍。通过这些维度的解析，您将更全面地了解 Apifox Helper 的功能设计及其在实际应用中的价值。

1. web 框架

1.1 spring框架

Apifox Helper 默认支持 Spring 框架，其识别逻辑如下：

类级别识别 ：在代码的类上检测 @Controller 或 @RestController 注解。
方法级别识别 ：在方法上检测 @RequestMapping、@GetMapping、@PostMapping 等注解。

只有当类和方法上的注解同时生效时，Apifox Helper 才会将其识别为一个 API。

参数识别规则：

默认识别 ：参数默认为 query 参数。
JSON 参数 ：如果方法参数中包含 @RequestBody 注解，则识别为 JSON 参数。
Form-data 参数 ：如果方法参数中包含 @ModelAttribute 注解，则识别为 form-data 参数。

Apifox 对一些常见的逻辑进行了特殊处理，您可以在 设置 -> 代码识别 -> 内置规则 -> Spring 框架 -> 高级配置 中找到相关配置。

1.1.1 泛型类型的处理

当您的入参被 Spring 的 HttpEntity 或类似类通过泛型包裹时（例如 HttpEntity<User>），Apifox 不会解析外层容器（如 HttpEntity），而是直接提取泛型中的类型（如 User）并上传到 Apifox。您也可以根据需要关闭此功能。

以下是默认支持的泛型类型及其处理规则：

bash 复制代码

org.springframework.http.HttpEntity<User> -> User
org.springframework.http.HttpEntity -> Object
org.springframework.http.RequestEntity<User> -> User
org.springframework.http.RequestEntity -> Object 
org.springframework.http.ResponseEntity<User> -> User
org.springframework.http.ResponseEntity-> Object
org.springframework.web.context.request.async.DeferredResult<User> -> User 
rg.springframework.web.context.request.async.DeferredResult -> Object
org.reactivestreams.Publisher<User> -> User
org.reactivestreams.Publisher -> Object

实现逻辑解析

上述功能的实现基于以下规则配置：

bash 复制代码

json.rule.convert[#regex:org.springframework.http.HttpEntity<(.*?)>]=${1}
json.rule.convert[org.springframework.http.HttpEntity]=java.lang.Object
json.rule.convert[#regex:org.springframework.http.RequestEntity<(.*?)>]=${1}
json.rule.convert[org.springframework.http.RequestEntity]=java.lang.Object
json.rule.convert[#regex:org.springframework.http.ResponseEntity<(.*?)>]=${1}
json.rule.convert[org.springframework.http.ResponseEntity]=java.lang.Object
json.rule.convert[#regex:org.springframework.web.context.request.async.DeferredResult<(.*?)>]=${1}
json.rule.convert[org.springframework.web.context.request.async.DeferredResult]=java.lang.Object
json.rule.convert[#regex:org.reactivestreams.Publisher<(.*?)>]=${1}
json.rule.convert[org.reactivestreams.Publisher]=java.lang.Object

自定义规则：实现类似能力（重要）

==通过上述逻辑，我们可以思考：是否可以为自定义的泛型类型实现类似的能力？==

==例如，如果您有一个带泛型的返回值对象 ====Result<T>====，并且不希望将 ====Result==== 的属性上传，而是仅提取泛型中的类型，您可以按照以下方式配置：==

bash 复制代码

json.rule.convert[com.apifox.Result]=java.lang.Object
json.rule.convert[#regex:com.apifox.Result<(.*?)>]=${1}

配置后，当插件遇到 Result<T> 时，会自动提取泛型中的类型，而忽略 Result 本身的属性。

1.1.2 读取 Spring 框架中的前置 URL

在微服务架构中，通常存在多个模块，每个模块通过网关访问，并拥有自己的统一前缀。为了适应这种开发模式，Apifox Helper 提供了一种默认扫描机制，用于识别模块的前置 URL。

默认配置文件扫描路径

Apifox Helper 会扫描以下配置文件，以获取 server.servlet.context-path 或 server.context-path 配置项：

bash 复制代码

/src/main/resources/bootstrap.yaml
/src/main/resources/bootstrap.properties
/src/main/resources/bootstrap.yml
/src/main/resources/application.properties
/src/main/resources/application.yml
/src/main/resources/application.yaml

如果配置文件中定义了 server.servlet.context-path=good，而 API 路径为 /apifox/test，则 Apifox Helper 会自动拼接为完整路径：good/apifox/test。

实现原理

bash 复制代码

properties.additional=${module_path}/src/main/resources/bootstrap.yaml
properties.additional=${module_path}/src/main/resources/bootstrap.properties
properties.additional=${module_path}/src/main/resources/bootstrap.yml
properties.additional=${module_path}/src/main/resources/application.properties
properties.additional=${module_path}/src/main/resources/application.yml
properties.additional=${module_path}/src/main/resources/application.yaml
class.prefix.path=${server.servlet.context-path}
class.prefix.path=${server.context-path}

自定义规则：实现类似能力（重要）

==如果您希望指定自定义配置文件（例如 ====application-dev.properties====），并定义自己的前置 URL 逻辑，可以按照以下方式配置：==

bash 复制代码

properties.additional=${module_path}/src/main/resources/bootstrap-dev.yml
class.prefix.path=${apifox.context-path}

在 bootstrap-dev.yml 配置文件中，定义 apifox.context-path，该值将作为当前模块所有 API 的前置 URL。

2. 强大的校验库支持

Apifox Helper 提供了对多种校验库的全面支持，包括 Jakarta Validation 和 Javax Validation。通过这些校验库，您可以轻松实现以下功能：

参数必填选项：自动识别校验注解，标记必填参数。
数据格式校验：支持邮箱、URL、正则表达式等格式校验。
Mock 数据生成：根据校验规则生成符合要求的 Mock 数据（如邮箱、电话号码等）。

支持的注解及其能力

以下是 Apifox Helper 支持的常用校验注解及其功能描述：

注解	能力描述
`@NotNull`	用于必填参数校验。
`@NotBlank`	用于必填参数校验。
`@NotEmpty`	用于必填参数校验。
`@AssertFalse`	标记字段必须为 `false`，用于布尔值校验。
`@AssertTrue`	标记字段必须为 `true`，用于布尔值校验。
`@DecimalMax`	标记字段值必须小于或等于指定最大值（支持小数），用于数值范围校验。
`@DecimalMin`	标记字段值必须大于或等于指定最小值（支持小数），用于数值范围校验。
`@Digits`	标记字段值必须符合指定的整数和小数位数，用于数值格式校验。
`@Email`	标记字段值必须为有效的邮箱格式，用于邮箱格式校验和 Mock 数据生成。
`@Max`	标记字段值必须小于或等于指定最大值（整数），用于数值范围校验。
`@Min`	标记字段值必须大于或等于指定最小值（整数），用于数值范围校验。
`@Negative`	标记字段值必须为负数，用于数值校验。
`@NegativeOrZero`	标记字段值必须为负数或零，用于数值校验。
`@Pattern`	标记字段值必须符合指定的正则表达式，用于自定义格式校验。
`@Positive`	标记字段值必须为正数，用于数值校验。
`@PositiveOrZero`	标记字段值必须为正数或零，用于数值校验。
`@Size`	标记字段值（字符串、集合、数组等）的长度必须在指定范围内，用于长度校验。
`@Length` (Hibernate)	标记字符串长度必须在指定范围内，用于字符串长度校验。
`@Range` (Hibernate)	标记字段值必须在指定范围内（支持整数和小数），用于数值范围校验。

通过以上注解，Apifox Helper 能够自动识别校验规则，并将其应用于 API 文档的生成和 Mock 数据的创建，帮助您更高效地管理和测试 API。

在参数校验中，必填和允许为 null 是两个不同的概念：我将在后续章节中详细讲解如何配置允许为 null 的字段，敬请期待！

3. 序列化库支持

Apifox Helper 支持多种流行的序列化库，确保您能够灵活地处理 API 参数的序列化和反序列化。以下是支持的序列化库及其功能详情：

3.1 FastJson

支持功能：
- 支持 @JSONField 注解的 name 属性，将其作为上传到 Apifox 的参数 key 的名称。
- 支持 @JSONField 注解的 serialize 属性，若设置为 false，则该字段不会上传到 Apifox。

3.2 Jackson

支持功能 ：
- 支持 @JsonProperty 注解的 value 属性，将其作为上传到 Apifox 的参数 key 的名称。
- 支持 @JsonProperty 注解的 defaultValue 属性，将其作为上传到 Apifox 的参数 value 的值。
- 支持 @JsonIgnore 注解的 value 属性，若设置为 true，则该字段不会上传到 Apifox。
- 支持 @JsonFormat 注解的 pattern 属性，设置日期的 mock 例如 @datetime("yyyy-MM-dd")
- 支持 @JsonProperty 注解的 index 属性，设置上传到 Apifox 的参数的顺序
- 动态识别 @JsonIgnoreProperties 注解中指定的字段，并在 API 文档生成过程中忽略这些字段。
- 解析 @JsonUnwrapped 注解的 prefix 和 suffix 属性，动态调整字段名称，这个仅支持生成 JSON 、 JSON5、Properties
- 分组上传 ：通过 @JsonView 注解，可以为不同的字段设置不同的视图分组。动态忽略：在 API 文档生成过程中，根据当前视图分组动态忽略不需要上传的字段。

3.3 GSON

支持功能：
- 支持 @SerializedName 注解的 value 属性，将其作为上传到 Apifox 的参数 key 的名称。
- 支持 @Expose 注解的 serialize 属性，若设置为 false，则该字段不会上传到 Apifox。

4. 识别OpenAPI

Apifox Helper 提供了对 Swagger 注解的全面支持，帮助开发者快速生成规范的 API 文档。以下是支持的 Swagger 注解及其功能说明：

4.1 Swagger 的注解支持

API 操作相关注解

@ApiOperation：
- API 名称，取自 value 属性。
- API 描述，取自 notes 属性。
- API 标签，取自 tags 属性。
- 是否隐藏 API，取自 hidden 属性。

API 参数相关注解

@ApiParam：
- 参数描述，取自 value 属性。
- 参数是否必填，取自 required 属性。
- 参数名称，取自 name 属性。
- 参数默认值或示例值，取自 example 或 defaultValue 属性。
- 是否隐藏参数，取自 hidden 属性。

API 分组相关注解

@Api：
- 生成 API 的文件夹名称，取自 value 或 tags 属性。
- 是否隐藏 API ，取自 hidden 属性。

API 模型相关注解

@ApiModel：
- 模型描述，取自 value 或 description 属性。
@ApiModelProperty：
- 字段名称，取自 name 属性。
- 是否隐藏字段，取自 hidden 属性。
- 字段描述，取自 value 或 notes 属性。
- 字段是否必填，取自 required 属性。

API 标签相关注解

@Tag：
- 标签名称，取自 value 属性。

Swagger 高级功能

@ApiImplicitParam 和 @ApiImplicitParams
- 支持解析隐式参数，动态设置参数类型（query、form、path、header）及其描述、示例值和必填属性。
@ApiResponse 和 @ApiResponses
- 支持解析 API 响应，动态设置响应码、响应描述、响应头和响应体。
- 支持将响应体的 JSON 结构嵌入 API 描述中，便于开发者查看。

4.2 OpenAPI 的注解支持

隐藏字段与参数

@Hidden：
- 标记类、方法、字段或参数为隐藏，不会上传到 Apifox。
@Schema(hidden=true)：
- 标记字段或参数为隐藏，不会上传到 Apifox。

API 操作相关注解

@Operation：
- API 名称，取自 summary 属性。
- API 操作 ID，取自 operationId 属性。
- API 描述，取自 summary 或 description 属性。
- 默认 HTTP 方法，取自 method 属性。
- API 标签，取自 tags 属性。
- 标记 API 为已弃用，取自 deprecated 属性。

API 标签相关注解

@Tag：
- 生成 API 的文件夹名称，取自 name 属性。
- API 标签，取自 name 属性。
@Tags：
- 支持多个标签，动态提取标签名称

参数相关注解

@Parameter：
- 是否隐藏参数，取自 hidden 属性。
- 参数描述，取自 description 属性。
- 参数是否必填，取自 required 属性。
- 参数默认值，取自 defaultValue 属性。
@RequestBody：
- 请求体描述，取自 description 属性。
- 请求体是否必填，取自 required 属性。

模型相关注解

@Schema：
- 字段描述，取自 description 属性。
- 字段名称，取自 name 属性。
- 字段默认值，取自 defaultValue 属性。
- 字段示例值，取自 example 属性。
- 字段是否必填，取自 required 属性。
- 模型描述，取自 name 属性。
- 动态判断参数是否必填，取自 requiredMode 属性。
- 标记模型为已弃用，取自 deprecated 属性。
anyOf、allOf、oneOf：
- 支持 OpenAPI 3.0 的组合模式，动态解析字段的组合规则。

参数与响应解析

支持从 @Parameter、@Parameters 和 @Operation.parameters 中提取参数信息，动态设置参数类型（query、form、path、header）及其描述、示例值和必填属性。

5. Java DTO 枚举值与字段处理规则

在 Java DTO（数据传输对象）中，Apifox Helper 提供了对枚举值和字段的智能处理规则，确保生成的 API 文档准确且符合开发需求。以下是详细的处理规则：

枚举值处理

非枚举类字段：
- 如果字段类型不是枚举类，但通过 @see 注释引用了枚举类，Apifox Helper 会从引用的枚举类中提取枚举值。
- 提取的枚举值优先级：
  1. 枚举常量的名称。
  2. 枚举常量中与 DTO 字段类型或字段名相同的字段的值。
  3. 枚举常量的索引。
枚举类字段：
- 直接提取枚举常量的名称、值和索引，用于生成 API 文档中的枚举值描述。

字段处理规则

忽略字段：
- 忽略标记为 transient 的字段。
- 忽略 serialVersionUID 字段。
识别字段：
- 识别标记为 static 或 static final 的字段。
- 只识别标记为 private 或 protected 的字段。
方法同名接口：
- 识别与 Object 类方法同名的方法（如 toString() 或 hashCode()），但不会将其作为 API 文档的一部分。

Javadoc 注释处理

@module 注释：
- 使用 @module 注释覆盖当前项目的模块名称。
@ignore 注释：
- 使用 @ignore 注释指定不导出某些字段或方法。

总结

Apifox Helper 提供了灵活的配置选项和强大的功能支持，覆盖 Spring 框架、校验库、序列化库、OpenAPI 注解和 Java DTO 处理等多个方面。无论是泛型处理、校验规则还是枚举值提取，Apifox Helper 都能满足多样化的开发需求，帮助开发者高效生成规范的 API 文档。