Apifox IDEA 插件使用指南 - 从入门到精通（4）引言 Apifox Helper：解锁自定义规则的无限可能

引言

Apifox Helper：解锁自定义规则的无限可能

除了内置的丰富规则，Apifox Helper 还为您提供了强大的自定义规则功能，让您能够根据实际需求灵活编写规则，轻松应对各种特殊场景。无论您是处理复杂的数据转换，还是优化特定的工作流程，自定义规则都能为您提供精准的解决方案。

在本章中，我们将带您深入探索 Apifox Helper 自定义规则的编写方法，并分享一些预设的自定义规则示例，助您快速上手并熟练掌握这一强大功能。通过 Apifox 提供的实际案例，您将逐步学会如何编写高效、实用的自定义规则。

Github 代码地址：
👉 github.com/apifox/apif…

此外，基于对官方文档的深入理解以及实际应用中的经验总结，我将为您系统梳理和分类各种规则，并结合具体场景举例说明，帮助您更清晰地理解每条规则的核心价值与应用方法。

1. 方法（Method）相关规则

1.1 API 配置：`api.name` 规则详解

功能描述
api.name 用于设置 API 接口的名称。默认情况下，系统会提取 API 注释的第一行作为接口名称。通过自定义规则，您可以从特定标签（如 @api.name 或自定义注解）中读取接口名称，从而更灵活地定义 API 的命名。

配置方法

在配置文件中，您可以通过以下方式定义 api.name 规则：

# 从 `@api.name` 标签中读取 API 名称
api.name=#api.name

# 从自定义注解 `@com.example.springtest.anno.ApiName` 中读取 API 名称
api.name=@com.example.springtest.anno.ApiName

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用 @api.name 标签和自定义注解 @ApiName 定义 API 名称：

package com.example.springtest.controller;

import com.example.springtest.anno.ApiName;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping(value = "/apiNameClass")
public class ApiNameController {

    /**
     * @api.name APINAME_TEST
     * @return
     */
    @GetMapping("/apiNameClassDoc")
    public String apiNameClassDoc() {
        return "apiNameClass";
    }

    @ApiName("apiNameClassAnno")
    @GetMapping("/apiNameClassAnno")
    public String apiNameClassAnno() {
        return "apiNameClass";
    }
}

示例解析

通过 @api.name 标签定义名称
- 在 apiNameClassDoc 方法的注释中，使用 @api.name APINAME_TEST 明确指定了该 API 的名称为 "APINAME_TEST"。
- 系统会根据配置的 api.name=#api.name 规则，从注释中提取名称。
通过自定义注解 @ApiName 定义名称
- 在 apiNameClassAnno 方法中，使用 @ApiName("apiNameClassAnno") 注解指定了该 API 的名称为 "apiNameClassAnno"。
- 系统会根据配置的 api.name=@com.example.springtest.anno.ApiName 规则，从注解中提取名称。
默认行为
- 如果没有配置 api.name 规则，系统会默认使用注释的第一行作为 API 名称。

适用场景

当 API 注释的第一行不适合作为接口名称时，可以通过 @api.name 或自定义注解灵活定义名称。
在团队协作中，统一 API 命名规范，提升代码可读性和维护性。
支持从多种来源（注释标签、自定义注解）提取名称，满足不同项目的需求。

导出结果

在这里插入图片描述

1.2 API 配置：`api.tags` 规则详解

功能描述
api.tags 用于设置 Apifox 的请求标签。默认情况下，系统会使用逗号（,）分割多个标签。通过自定义规则，您可以从特定标签（如 @tags 或自定义注解）中读取标签信息，从而更灵活地管理 API 的分类和组织。

配置方法

在配置文件中，您可以通过以下方式定义 api.tags 规则：

# 从 `@tags` 标签中读取请求标签
api.tags=#tags

# 从自定义注解 `@com.example.springtest.anno.ApiTag` 中读取请求标签
api.tags=@com.example.springtest.anno.ApiTag

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用 @tags 标签和自定义注解 @ApiTag 定义请求标签：

package com.example.springtest.controller;

import com.example.springtest.anno.ApiTag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/apiTagsController")
public class ApiTagsController {

    /**
     * @tags tag1,tag2
     * @return
     */
    @GetMapping({"/apiTagsControllerDocTag1", "/apiTagsControllerDocTag2"})
    public String apiTagsControllerDoc() {
        return "apiNameClass";
    }

    @ApiTag("tag3,tag4")
    @GetMapping("/apiTagsControllerAnno")
    public String apiTagsControllerAnno() {
        return "apiNameClass";
    }
}

示例解析

通过 @tags 标签定义标签
- 在 apiTagsControllerDoc 方法的注释中，使用 @tags tag1,tag2 明确指定了该 API 的标签为 "tag1" 和 "tag2"。
- 系统会根据配置的 api.tags=#tags 规则，从注释中提取标签。
通过自定义注解 @ApiTag 定义标签
- 在 apiTagsControllerAnno 方法中，使用 @ApiTag("tag3,tag4") 注解指定了该 API 的标签为 "tag3" 和 "tag4"。
- 系统会根据配置的 api.tags=@com.example.springtest.anno.ApiTag 规则，从注解中提取标签。
默认行为
- 如果没有配置 api.tags 规则，系统会默认使用逗号（,）分割标签。

适用场景

当需要为 API 添加分类或组织标签时，可以通过 @tags 或自定义注解灵活定义。
在团队协作中，统一标签规范，提升 API 的可管理性和可搜索性。
支持从多种来源（注释标签、自定义注解）提取标签，满足不同项目的需求。

导出结果

在这里插入图片描述

1.3 API 配置：`api.status` 规则详解

功能描述
api.status 用于设置 API 的请求状态。默认状态下，系统支持以下状态：

designing（设计中）
pending（待处理）
developing（开发中）
integrating（集成中）
testing（测试中）
tested（已测试）
released（已发布）
deprecated（已弃用）
exception（异常）
obsolete（已过时）

通过自定义规则，您可以从特定标签（如 @obsolete、@designing）或自定义注解（如 @Testing）中读取状态信息，从而更灵活地管理 API 的生命周期。

配置方法

在配置文件中，您可以通过以下方式定义 api.status 规则：

# 将自定义注解 `@com.example.springtest.anno.Testing` 映射为状态 `testing`
# apifox 注释已经内置了
api.status[@com.example.springtest.anno.Testing]=testing

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用内置标签和自定义注解定义 API 状态：

package com.example.springtest.controller;

import com.example.springtest.anno.Testing;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/apiStatusController")
public class ApiStatusController {

    /**
     * @obsolete
     */
    @GetMapping("/obsoleteClassDoc")
    public String obsoleteClassDoc() {
        return "obsolete";
    }

    /**
     * @designing
     */
    @GetMapping("/designingClassDoc")
    public String designingClassDoc() {
        return "designing";
    }

    @GetMapping("/testingClassDoc")
    @Testing
    public String testingClassDoc() {
        return "testing";
    }
}

示例解析

通过内置标签定义状态
- 在 obsoleteClassDoc 方法的注释中，使用 @obsolete 标签明确指定了该 API 的状态为 "obsolete"（已过时）。
- 在 designingClassDoc 方法的注释中，使用 @designing 标签明确指定了该 API 的状态为 "designing"（设计中）。
通过自定义注解定义状态
- 在 testingClassDoc 方法中，使用 @Testing 注解指定了该 API 的状态为 "testing"（测试中）。
- 系统会根据配置的 api.status[@com.example.springtest.anno.Testing]=testing 规则，将注解映射为状态。
默认行为
- ==系统内置了常见状态标签，无需额外配置即可直接使用。==

适用场景

当需要为 API 标记生命周期状态时，可以通过内置标签或自定义注解灵活定义。
在团队协作中，统一状态管理规范，提升 API 的可维护性和可追踪性。
支持从多种来源（内置标签、自定义注解）提取状态，满足不同项目的需求。

导出结果

在这里插入图片描述

1.4 API 配置：`method.description` 规则详解

功能描述
method.description 用于设置 API 接口的详细说明，作为方法（API）的额外注释。通过自定义规则，您可以从特定标签（如 @desc）或自定义注解（如 @Desc）中读取描述信息，从而为 API 提供更丰富的文档支持。

配置方法

在配置文件中，您可以通过以下方式定义 method.description 规则：

# 从 `@desc` 标签中读取接口描述
method.description=#desc

# 从自定义注解 `@com.example.springtest.anno.Desc` 中读取接口描述
method.description=@com.example.springtest.anno.Desc

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用 @desc 标签和自定义注解 @Desc 定义 API 接口说明：

package com.example.springtest.controller;

import com.example.springtest.anno.Desc;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/methodDescController")
public class MethodDescController {

    /**
     * 名字1
     * @desc doc描述
     */
    @GetMapping("/methodDescClassDoc")
    public String methodDescClassDoc() {
        return "methodDescClassDoc";
    }

    /**
     * 名字2
     * @return
     */
    @GetMapping("/methodDescClassAnno")
    @Desc("注解描述")
    public String methodDescClassAnno() {
        return "methodDescClassAnno";
    }
}

示例解析

通过 @desc 标签定义接口描述
- 在 methodDescClassDoc 方法的注释中，使用 @desc doc描述 明确指定了该 API 的接口描述为 "doc描述"。
- 系统会根据配置的 method.description=#desc 规则，从注释中提取描述。
通过自定义注解 @Desc 定义接口描述
- 在 methodDescClassAnno 方法中，使用 @Desc("注解描述") 注解指定了该 API 的接口描述为 "注解描述"。
- 系统会根据配置的 method.description=@com.example.springtest.anno.Desc 规则，从注解中提取描述。
默认行为
- 如果没有配置 method.description 规则，系统会默认使用注释的第一行作为接口描述。

适用场景

当需要为 API 提供详细的接口说明时，可以通过 @desc 或自定义注解灵活定义。
在团队协作中，统一接口描述规范，提升代码的可读性和文档质量。
支持从多种来源（注释标签、自定义注解）提取描述，满足不同项目的需求。

导出结果

在这里插入图片描述

1.5 API 配置：`method.defaultContentType` 规则详解

功能描述
method.defaultContentType 用于设置 API 请求的默认 Content-Type。插件会在必要时强制覆盖该值，例如当遇到 @RequestBody 注解时，Content-Type 会被强制设置为 application/json。

通过自定义规则，您可以从特定标签（如 @methodType）中读取 Content-Type 信息，从而更灵活地定义 API 的请求格式。

配置方法

在配置文件中，您可以通过以下方式定义 method.defaultContentType 规则：

# 从 `@methodType` 标签中读取默认 Content-Type
method.defaultContentType[#methodType]=#methodType

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用 @methodType 标签定义 API 请求的默认 Content-Type：

package com.example.springtest.controller;

import com.example.springtest.anno.ParamType;
import com.example.springtest.entity.User;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping(value = "/methodDefaultContentTypeController")
public class MethodDefaultContentTypeController {

    /**
     * @methodType multipart/form-data
     * Get请求默认是query，规则无法生效
     */
    @GetMapping("/formDataClassDocGet")
    public String formDataClassDocGet(@ParamType("form") User data) {
        return "originalClass";
    }

    /**
     * @methodType multipart/form-data
     * @desc 规则之间需要搭配使用，@methodType 与 @ParamType 需要搭配使用才行
     */
    @PostMapping("/formDataClassDocPost")
    public String formDataClassDocPost(@ParamType("form") User data) {
        return "originalClass";
    }

    /**
     * @methodType application/json
     * @desc 规则之间需要搭配使用，@methodType 与 @ParamType 需要搭配使用才行
     */
    @PostMapping("/formDataClassDocPostJson")
    public String formDataClassDocPostJson(@ParamType("body") User data) {
        return "originalClass";
    }
}

示例解析

通过 @methodType 标签定义默认 Content-Type
- 在 formDataClassDocPost 方法的注释中，使用 @methodType multipart/form-data 明确指定了该 API 的默认 Content-Type 为 "multipart/form-data"。
- 在 formDataClassDocPostJson 方法的注释中，使用 @methodType application/json 明确指定了该 API 的默认 Content-Type 为 "application/json"。
规则搭配使用
- @methodType 需要与 @ParamType 搭配使用，以确保请求参数的格式与 Content-Type 一致。
- 例如，@ParamType("form") 表示参数以表单形式传递，而 @ParamType("body") 表示参数以 JSON 形式传递。
默认行为
- 对于 GET 请求，默认的 Content-Type 为 query，此时 @methodType 规则不会生效。
- 当遇到 @RequestBody 注解时，Content-Type 会被强制覆盖为 application/json。

适用场景

当需要为 API 设置特定的 Content-Type 时，可以通过 @methodType 标签灵活定义。
在团队协作中，统一请求格式规范，提升 API 的可维护性和一致性。
支持与其他规则（如 @ParamType）搭配使用，确保请求参数与 Content-Type 匹配。

导出结果

在这里插入图片描述

1.6 API 配置：`method.request.replace` 规则详解

功能描述
method.request.replace 用于设置传入参数的命名方式转换规则，支持以下命名格式：

camelCase（小驼峰）
pascalCase（大驼峰）
snakeCase（下划线）
flatcase（全小写）
uppercase（全大写）
macroCase（全大写下划线）
titleCase（大驼峰下划线）

此规则的优先级低于全局配置。如果希望使用此规则，请确保全局配置中的参数命名方式设置为“保持原样”。

配置方法

在配置文件中，您可以通过以下方式定义 method.request.replace 规则：

# 从 `@requestCase` 标签中读取命名方式
method.request.replace[#requestCase]=#requestCase

# 从自定义注解 `@com.example.springtest.anno.RequestCase` 中读取命名方式
method.request.replace[@com.example.springtest.anno.RequestCase]=@com.example.springtest.anno.RequestCase#value

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用 @requestCase 标签和自定义注解 @RequestCase 定义参数命名方式：

package com.example.springtest.controller;

import com.example.springtest.anno.RequestCase;
import com.example.springtest.entity.Case;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/methodRequestReplace")
public class MethodRequestController {

    /**
     * @requestCase snakeCase
     * @return
     */
    @GetMapping("/snakeCaseClassDoc")
    public String snakeCaseClassDoc(Case user) {
        return "snakeCase";
    }

    @RequestCase("snakeCase")
    @GetMapping("/snakeCaseClassAnno")
    public String snakeCaseClassAnno(Case user) {
        return "snakeCase";
    }

    @GetMapping("/noChangeCaseClassAnno")
    public String noChangeCaseClassAnno(Case user) {
        return "noChangeCaseClassAnno";
    }
}

示例解析

通过 @requestCase 标签定义命名方式
- 在 snakeCaseClassDoc 方法的注释中，使用 @requestCase snakeCase 明确指定了参数命名方式为 "snakeCase"（下划线格式）。
- 系统会根据配置的 method.request.replace[#requestCase]=#requestCase 规则，从注释中提取命名方式。
通过自定义注解 @RequestCase 定义命名方式
- 在 snakeCaseClassAnno 方法中，使用 @RequestCase("snakeCase") 注解指定了参数命名方式为 "snakeCase"（下划线格式）。
- 系统会根据配置的 method.request.replace[@com.example.springtest.anno.RequestCase]=@com.example.springtest.anno.RequestCase#value 规则，从注解中提取命名方式。
默认行为
- 如果没有配置 method.request.replace 规则，系统会保持参数命名方式不变（即“保持原样”）。

适用场景

当需要统一参数命名格式时，可以通过 @requestCase 或自定义注解灵活定义。
在团队协作中，统一命名规范，提升代码的可读性和一致性。
支持从多种来源（注释标签、自定义注解）提取命名方式，满足不同项目的需求。

导出结果

在这里插入图片描述

1.7 API 配置：`method.response.replace` 规则详解

1.7 与 1.6 使用方式一致，在这里不重复赘述

1.8 API 配置：`method.additional.header` 规则详解

功能描述
method.additional.header 用于为 API 接口添加额外的请求头信息。例如，所有接口可能需要在请求头中携带 JWT Token。通过自定义规则，您可以为特定接口或全局接口配置请求头，并支持排除某些开放的接口（如公开接口）。

配置方法

在配置文件中，您可以通过以下方式定义 method.additional.header 规则：

全局配置
为所有接口添加请求头：

method.additional.header={name: "AllAuthorizationYourSelf", value: "result", description: "my Token", required: true}

通过注释标签配置
为带有 @header 标签的接口添加请求头：

method.additional.header[#header]={name: "DocAuthorizationYourSelf", value: "docresult", description: "my Token Doc", required: true}

通过自定义注解配置
为带有 @com.example.springtest.anno.Header 注解的接口添加请求头：

method.additional.header[@com.example.springtest.anno.Header]={name: "AnnoAuthorizationYourSelf", value: "Annoresult", description: "my Token Anno", required: true}

排除公开接口
为所有非公开接口添加请求头：

method.additional.header[!@com.apifox.common.annotation.Public]={name: "Authorization", value: "", description: "认证 Token", required: true}

等价于：

method.additional.header[groovy:!it.hasAnn("com.apifox.common.annotation.Public")]={name: "Authorization", value: "", description: "认证 Token", required: true}

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用注释标签和自定义注解定义额外请求头：

package com.example.springtest.controller;

import com.example.springtest.anno.Header;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/methodHeaderController")
public class MethodHeaderController {

    @GetMapping("/methodHeader")
    public String methodHeader() {
        return null;
    }

    /**
     * @header
     * @return
     */
    @GetMapping("/methodHeaderDoc")
    public String methodHeaderDoc() {
        return null;
    }

    @Header
    @GetMapping("/methodHeaderAnno")
    public String methodHeaderAnno() {
        return null;
    }
}

示例解析

全局请求头

所有接口（如 methodHeader）都会自动添加请求头：

{
  "name": "AllAuthorizationYourSelf",
  "value": "result",
  "description": "my Token",
  "required": true
}

通过注释标签添加请求头

在 methodHeaderDoc 方法的注释中，使用 @header 标签为该接口添加请求头：

{
  "name": "DocAuthorizationYourSelf",
  "value": "docresult",
  "description": "my Token Doc",
  "required": true
}

通过自定义注解添加请求头

在 methodHeaderAnno 方法中，使用 @Header 注解为该接口添加请求头：

{
  "name": "AnnoAuthorizationYourSelf",
  "value": "Annoresult",
  "description": "my Token Anno",
  "required": true
}

排除公开接口

如果接口标记为 @Public，则不会添加请求头；否则，会添加以下请求头：

{
  "name": "Authorization",
  "value": "",
  "description": "认证 Token",
  "required": true
}

适用场景

当需要为所有接口或特定接口添加固定请求头（如 JWT Token）时，可以通过全局配置、注释标签或自定义注解实现。
在团队协作中，统一请求头规范，提升 API 的安全性和一致性。
支持排除公开接口，确保某些接口无需携带额外请求头。

导出结果

在这里插入图片描述

1.9 API 配置：`method.additional.param` 规则详解

1.9 与 1.8 使用方式一致，在这里不重复赘述

1.10 API 配置：`method.return` 规则详解

功能描述
method.return 用于设置方法的返回值类型，特别是当方法的实际返回类型与声明的返回类型不一致时。例如：

方法返回 void，但实际通过 HttpServletResponse 返回 JSON 数据。
方法返回类型中的泛型未明确（如 <Object>、<?>、<*>）。
方法返回类型与实际响应无关，需要通过额外配置明确实际响应类型。

通过 method.return 规则，可以从注释标签（如 @response）或自定义注解中提取实际返回类型，确保 API 文档与实际行为一致。

配置方法

在配置文件中，您可以通过以下方式定义 method.return 规则：

从注释标签中提取返回值类型
```
method.return=#response
```

从自定义注解中提取返回值类型

method.return[@com.example.springtest.anno.Response]=@com.example.springtest.anno.Response#value

使用 Groovy 脚本解析 {@link} 标签

method.return[#responseLink]=groovy: helper.resolveLink(it.doc("responseLink"))

简化配置：直接解析 @response 标签中的 {@link}

method.return[#response]=groovy: helper.resolveLink(it.doc("response"))

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用 method.return 规则：

package com.example.springtest.controller;

import com.example.springtest.anno.Response;
import com.example.springtest.entity.R;
import com.example.springtest.entity.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/methodReturnController")
public class MethodReturnController {

    @GetMapping("/methodReturnNoChange")
    public User methodReturnNoChange() {
        return null;
    }

    @GetMapping("/methodReturnNoChangeR")
    public R<User> methodReturnNoChangeR() {
        return null;
    }

    /**
     * @response com.example.springtest.entity.R<com.example.springtest.entity.User>
     */
    @GetMapping("/methodReturnChangeDoc")
    public User methodReturnChangeDoc() {
        return null;
    }

    @Response("com.example.springtest.entity.R<com.example.springtest.entity.User>")
    @GetMapping("/methodReturnChangeAnno")
    public User methodReturnChangeAnno() {
        return null;
    }

    /**
     * @responseLink {@link R<User>}
     */
    @GetMapping("/methodReturnChangeDocLink")
    public User methodReturnChangeDocLink() {
        return null;
    }
}

示例解析

默认行为
- methodReturnNoChange 方法的返回类型为 User，系统会直接使用 User 作为返回值类型。
- methodReturnNoChangeR 方法的返回类型为 R<User>，系统会直接使用 R<User> 作为返回值类型。
通过注释标签定义返回值类型
- 在 methodReturnChangeDoc 方法的注释中，使用 @response 标签明确指定了返回值类型为 R<User>。
- 系统会根据配置的 method.return=#response 规则，从注释中提取返回值类型。
通过自定义注解定义返回值类型
- 在 methodReturnChangeAnno 方法中，使用 @Response 注解指定了返回值类型为 R<User>。
- 系统会根据配置的 method.return[@com.example.springtest.anno.Response]=@com.example.springtest.anno.Response#value 规则，从注解中提取返回值类型。
使用 {@link} 标签定义返回值类型
- 在 methodReturnChangeDocLink 方法的注释中，使用 @responseLink {@link R<User>} 标签指定了返回值类型。
- 系统会根据配置的 method.return[#responseLink]=groovy: helper.resolveLink(it.doc("responseLink")) 规则，解析 {@link} 标签并提取返回值类型。

适用场景

实际返回类型与声明类型不一致：例如通过 HttpServletResponse 返回 JSON 数据，但方法声明为 void。
泛型类型未明确：例如返回类型为 <Object>、<?> 或 <*>，需要通过额外配置明确具体类型。
统一返回值类型规范：在团队协作中，确保 API 文档与实际行为一致，提升代码可读性和维护性。
支持多来源配置：从注释标签、自定义注解或 {@link} 标签中提取返回值类型，满足不同项目的需求。

导出结果

在这里插入图片描述

1.11 API 配置：`method.return.body.type` 规则详解

功能描述
method.return.body.type 用于控制 API 返回值的响应类型，支持以下格式：

raw：原始文本格式
json：JSON 格式（默认）
xml：XML 格式
html：HTML 格式
binary：二进制格式
msgpack：MessagePack 格式
eventStream：事件流格式

通过该规则，您可以从注释标签（如 @returnType）或自定义注解中提取返回值类型，确保 API 响应的内容类型与实际行为一致。

配置方法

在配置文件中，您可以通过以下方式定义 method.return.body.type 规则：

从注释标签中提取返回值类型

method.return.body.type[#returnXml]=xml

从自定义注解中提取返回值类型

method.return.body.type[@com.example.springtest.anno.ReturnType]=@com.example.springtest.anno.ReturnType#value

默认行为
如果未配置 method.return.body.type 规则，系统会默认返回 JSON 格式。

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用 method.return.body.type 规则：

package com.example.springtest.controller;

import com.example.springtest.anno.ReturnType;
import com.example.springtest.entity.User;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

@Controller
@RequestMapping(value = "/methodReturnBodyController")
public class MethodReturnBodyController {

    @GetMapping("/methodReturnNoChange")
    public User methodReturnNoChange() {
        return null;
    }

    @GetMapping("/methodReturnNoChangeBody")
    @ResponseBody
    public User methodReturnNoChangeBody() {
        return null;
    }

    /**
     * @returnType application/xml
     */
    @GetMapping("/methodReturnDoc")
    public User methodReturnDoc() {
        return null;
    }

    @ReturnType("text/event-stream")
    @GetMapping("/methodReturnAnno")
    public User methodReturnAnno() {
        return null;
    }

    @GetMapping(value = "/methodReturnXml", produces = MediaType.APPLICATION_XML_VALUE)
    public User methodReturnXml() {
        return null;
    }

    @GetMapping(value = "/methodReturnStream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public User methodReturnStream() {
        return null;
    }

    @ReturnType("application/octet-stream")
    @GetMapping("/methodReturnAnnoBinary")
    public User methodReturnAnnoBinary() {
        return null;
    }

    @ReturnType("text/plain")
    @GetMapping("/methodReturnAnnoRow")
    public Void methodReturnAnnoRow() {
        return null;
    }
}

示例解析

默认行为
- methodReturnNoChange 和 methodReturnNoChangeBody 方法未指定返回值类型，系统会默认返回 JSON 格式。
通过注释标签定义返回值类型
- 在 methodReturnDoc 方法的注释中，使用 @returnType application/xml 标签明确指定了返回值类型为 XML 格式。
- 系统会根据配置的 method.return.body.type[#returnXml]=xml 规则，从注释中提取返回值类型。
通过自定义注解定义返回值类型
- 在 methodReturnAnno 方法中，使用 @ReturnType("text/event-stream") 注解指定了返回值类型为事件流格式。
- 系统会根据配置的 method.return.body.type[@com.example.springtest.anno.ReturnType]=@com.example.springtest.anno.ReturnType#value 规则，从注解中提取返回值类型。
通过 produces 属性定义返回值类型
- 在 methodReturnXml 方法中，使用 produces = MediaType.APPLICATION_XML_VALUE 指定了返回值类型为 XML 格式。
- 在 methodReturnStream 方法中，使用 produces = MediaType.TEXT_EVENT_STREAM_VALUE 指定了返回值类型为事件流格式。
其他返回值类型
- methodReturnAnnoBinary 方法通过 @ReturnType("application/octet-stream") 指定了返回值类型为二进制格式。
- methodReturnAnnoRow 方法通过 @ReturnType("text/plain") 指定了返回值类型为原始文本格式。

适用场景

统一返回值格式：在团队协作中，确保 API 响应的内容类型一致，提升代码可读性和维护性。
支持多种返回值类型：根据业务需求，灵活配置 JSON、XML、HTML、二进制等格式。
与实际行为一致：当方法的返回值类型与实际响应类型不一致时，通过额外配置明确响应类型。

导出结果

在这里插入图片描述

1.12 API 配置：`path.multi` 规则详解

功能描述
path.multi 用于处理 API 有多个可用路径时的策略选择。支持的策略包括（不区分大小写）：

FIRST：选择第一个可用路径。
LAST：选择最后一个可用路径。
LONGEST：选择最长的可用路径。
SHORTEST：选择最短的可用路径。
ALL：为每一个可用路径生成一个 API。

通过该规则，您可以从注释标签（如 @urlType）或自定义注解中提取路径选择策略，确保 API 路径的生成符合预期。

配置方法

在配置文件中，您可以通过以下方式定义 path.multi 规则：

从注释标签中提取路径选择策略
```
path.multi=#urlType
```

从自定义注解中提取路径选择策略

path.multi[@com.example.springtest.anno.UrlType]=@com.example.springtest.anno.UrlType#value

默认行为
如果未配置 path.multi 规则，系统会默认选择 ALL 策略。

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用 path.multi 规则：

package com.example.springtest.controller;

import com.example.springtest.anno.UrlType;
import com.example.springtest.entity.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/pathMultiController")
public class PathMultiController {

    @GetMapping({"/methodReturnOne", "/methodReturnTwo"})
    public User methodReturnOne() {
        return null;
    }

    /**
     * @urlType first
     */
    @GetMapping({"/methodReturnOneDocFirstDoc", "/methodReturnOneDocTwoDoc"})
    public User methodReturnOneDocFirstDoc() {
        return null;
    }

    @UrlType("first")
    @GetMapping({"/methodReturnOneDocFirstAnno", "/methodReturnOneDocTwoAnno"})
    public User methodReturnOneDocFirstAnno() {
        return null;
    }

    /**
     * @urlType last
     */
    @GetMapping({"/methodReturnOneDocLastDoc", "/methodReturnTwoDocLastDoc", "/methodReturnThreeDocLastDoc"})
    public User methodReturnOneDocLastDoc() {
        return null;
    }

    @UrlType("last")
    @GetMapping({"/methodReturnOneDocLastAnno", "/methodReturnTwoDocLastAnno", "/methodReturnLastDocLastAnno"})
    public User methodReturnOneDocLastAnno() {
        return null;
    }

    /**
     * @urlType all
     */
    @GetMapping({"/methodReturnOneDocAllDoc", "/methodReturnTwoDocAllDoc", "/methodReturnThreeDocAllDoc"})
    public User methodReturnOneDocAllDoc() {
        return null;
    }

    @UrlType("all")
    @GetMapping({"/methodReturnOneDocAllAnno", "/methodReturnTwoDocAllAnno", "/methodReturnLastDocAllAnno"})
    public User methodReturnOneDocAllAnno() {
        return null;
    }
}

示例解析

默认行为
- methodReturnOne 方法未指定路径选择策略，系统会默认选择 ALL 策略
通过注释标签定义路径选择策略
- 在 methodReturnOneDocFirstDoc 方法的注释中，使用 @urlType first 标签明确指定了路径选择策略为 FIRST。
- 系统会根据配置的 path.multi=#urlType 规则，从注释中提取策略并选择第一个路径 /methodReturnOneDocFirstDoc。
通过自定义注解定义路径选择策略
- 在 methodReturnOneDocFirstAnno 方法中，使用 @UrlType("first") 注解指定了路径选择策略为 FIRST。
- 系统会根据配置的 path.multi[@com.example.springtest.anno.UrlType]=@com.example.springtest.anno.UrlType#value 规则，从注解中提取策略并选择第一个路径 /methodReturnOneDocFirstAnno。
其他策略示例
- LAST 策略：
  - methodReturnOneDocLastDoc 方法使用 @urlType last 标签，选择最后一个路径 /methodReturnThreeDocLastDoc。
  - methodReturnOneDocLastAnno 方法使用 @UrlType("last") 注解，选择最后一个路径 /methodReturnLastDocLastAnno。
- ALL 策略：
  - methodReturnOneDocAllDoc 方法使用 @urlType all 标签，为所有路径生成独立的 API。
  - methodReturnOneDocAllAnno 方法使用 @UrlType("all") 注解，为所有路径生成独立的 API。

适用场景

多路径 API 处理：当 API 有多个可用路径时，根据业务需求选择合适的路径生成策略。
统一路径生成规范：在团队协作中，确保 API 路径生成的一致性，提升代码可读性和维护性。
灵活配置策略：支持从注释标签、自定义注解等多种来源提取路径选择策略，满足不同项目的需求。

导出结果

在这里插入图片描述

2. 参数（Parameter）相关规则

2.1 API 配置：`param.defaultValue` 规则详解

功能描述
param.defaultValue 用于设置 API 参数的默认值。通过该规则，您可以从自定义注解（如 @DefaultValue）中提取参数的默认值，确保 API 在未传入参数时使用预设的默认值。

配置方法

在配置文件中，您可以通过以下方式定义 param.defaultValue 规则：

从自定义注解中提取默认值

param.defaultValue[@com.example.springtest.anno.DefaultValue]=@com.example.springtest.anno.DefaultValue#value

默认行为
如果未配置 param.defaultValue 规则，系统不会为参数设置默认值。

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用 param.defaultValue 规则：

package com.example.springtest.controller;

import com.example.springtest.anno.DefaultValue;
import com.example.springtest.entity.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/paramDefaultController")
public class ParamDefaultController {

    /**
     * @param id 参数 ID
     * @return 返回值描述
     */
    @GetMapping("/paramDefault")
    public User paramDefault(@DefaultValue("默认数据") String id) {
        return null;
    }

}

示例解析

通过自定义注解设置默认值
- 在 paramDefault 方法中，使用 @DefaultValue("默认数据") 注解为 id 参数设置了默认值 "默认数据"。
- 系统会根据配置的 param.defaultValue[@com.example.springtest.anno.DefaultValue]=@com.example.springtest.anno.DefaultValue#value 规则，从注解中提取默认值。

适用场景

未传参数时的默认值：当 API 调用未传入参数时，使用预设的默认值，避免空值或异常。
统一参数默认值规范：在团队协作中，确保 API 参数的默认值一致，提升代码可读性和维护性。
增强 API 文档信息：通过描述信息，明确参数的用途和默认值，方便开发者理解和使用。

导出结果

在这里插入图片描述

2.2 API 配置：`param.description` 规则详解

功能描述
param.description 用于为 API 参数添加额外的注释信息，例如参数类型、描述等。通过该规则，您可以从注释标签、自定义注解或脚本中提取参数描述信息，增强 API 文档的可读性和实用性。

配置方法

在配置文件中，您可以通过以下方式定义 param.description 规则：

从自定义注解中提取描述信息

param.description[@com.example.springtest.anno.DefaultValue]=@com.example.springtest.anno.DefaultValue#desc

默认行为
如果未配置 param.description 规则，系统不会为参数添加额外的描述信息。

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用 param.description 规则：

package com.example.springtest.controller;

import com.example.springtest.anno.DefaultValue;
import com.example.springtest.entity.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/paramDefaultController")
public class ParamDefaultController {

    /**
     * @param id 描述 ID 拼接
     * @return 返回值描述是个用户
     */
    @GetMapping("/paramDefaultDesc")
    public User paramDefaultDesc(@DefaultValue(value = "默认数据Desc", desc = "描述ID") String id) {
        return null;
    }

}

示例解析

通过自定义注解提取描述信息
- 在 paramDefaultDesc 方法中，使用 @DefaultValue(value = "默认数据Desc", desc = "描述ID") 注解为 id 参数设置了描述信息 "描述ID"。
- 系统会根据配置的 param.description[@com.example.springtest.anno.DefaultValue]=@com.example.springtest.anno.DefaultValue#desc 规则，从注解中提取描述信息并添加到 API 文档中。

适用场景

增强 API 文档信息：为参数添加类型和描述信息，帮助开发者更好地理解和使用 API。
统一参数描述规范：在团队协作中，确保 API 参数的描述信息一致，提升代码可读性和维护性。
动态生成描述信息：通过脚本动态生成参数类型描述，减少手动维护成本。

导出结果

在这里插入图片描述

2.3 API 配置：`param.type` 规则详解

功能描述
param.type 用于设置 API 参数在 HTTP 请求中的类型（位置：body、form 或 query）。通过该规则，您可以灵活控制参数的传递方式，确保 API 请求符合预期。

注意：

如果参数使用了 @RequestBody、@ModelAttribute、@RequestHeader、@PathVariable 等注解，则忽略此规则。
如果参数使用了 @RequestParam 且 HTTP 方法为 GET，则忽略此规则。
如果未配置 param.type 规则，系统会默认将参数作为 query 传递。

配置方法

在配置文件中，您可以通过以下方式定义 param.type 规则：

从自定义注解中提取参数类型

param.type[@com.example.springtest.anno.ParamType]=@com.example.springtest.anno.ParamType#value

全局设置参数类型
- 将所有参数设置为 form 类型：
```
param.type=form
```
- 将 @RequestParam 注释参数作为 query，其他参数作为 form：
```
param.type[#requestParam]=query
param.type=form
```
默认行为
如果未配置 param.type 规则，系统会默认将参数作为 query 传递。

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用 param.type 规则：

package com.example.springtest.controller;

import com.example.springtest.anno.ParamType;
import com.example.springtest.entity.User;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping(value = "/methodDefaultContentTypeController")
public class MethodDefaultContentTypeController {

    /**
     * 将参数设置为 form 类型
     */
    @PostMapping("/paramTypeForm")
    public String paramTypeForm(@ParamType("form") User data) {
        return "paramTypeForm";
    }

    /**
     * 将参数设置为 body 类型
     */
    @PostMapping("/paramTypeBody")
    public String paramTypeBody(@ParamType("body") User data) {
        return "paramTypeBody";
    }

    /**
     * 将参数设置为 query 类型
     */
    @PostMapping("/paramTypeQuery")
    public String paramTypeQuery(@ParamType("query") User data) {
        return "paramTypeQuery";
    }
}

示例解析

通过自定义注解设置参数类型
- 在 paramTypeForm 方法中，使用 @ParamType("form") 注解将 data 参数设置为 form 类型。
- 系统会根据配置的 param.type[@com.example.springtest.anno.ParamType]=@com.example.springtest.anno.ParamType#value 规则，从注解中提取参数类型并应用到请求中。
设置参数为 body 类型
- 在 paramTypeBody 方法中，使用 @ParamType("body") 注解将 data 参数设置为 body 类型。
- 系统会将参数作为请求体传递。
设置参数为 query 类型
- 在 paramTypeQuery 方法中，使用 @ParamType("query") 注解将 data 参数设置为 query 类型。
- 系统会将参数作为查询参数传递。

适用场景

灵活控制参数传递方式：根据业务需求，将参数设置为 body、form 或 query 类型。
统一参数传递规范：在团队协作中，确保 API 参数的传递方式一致，提升代码可读性和维护性。
支持多种参数类型：满足不同场景下的参数传递需求，例如表单提交、JSON 请求体、URL 查询参数等。

导出结果

在这里插入图片描述

2.4 API 配置：`param.ignore` 规则详解

功能描述
param.ignore 用于忽略 API 中的某些参数，使其不参与请求处理或文档生成。通过该规则，您可以从自定义注解（如 @ParamIgnore）中标记需要忽略的参数，确保这些参数不会影响 API 的逻辑或文档。

配置方法

在配置文件中，您可以通过以下方式定义 param.ignore 规则：

从自定义注解中标记忽略参数

param.ignore[@com.example.springtest.anno.ParamIgnore]=true

默认行为
如果未配置 param.ignore 规则，系统不会忽略任何参数。

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用 param.ignore 规则：

package com.example.springtest.controller;

import com.example.springtest.anno.ParamIgnore;
import com.example.springtest.entity.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/paramIgnoreController")
public class ParamIgnoreController {

    @GetMapping("/paramIgnoreNoChange")
    public String paramIgnoreNoChange(String id, String sex, User user) {
        return "paramIgnoreNoChange";
    }

    @GetMapping("/paramIgnoreChange")
    public String paramIgnoreChange(@ParamIgnore String id, String sex, @ParamIgnore User user) {
        return "paramIgnoreChange";
    }
}

示例解析

默认行为
- 在 paramIgnoreNoChange 方法中，未使用 @ParamIgnore 注解，因此所有参数（id、sex、user）都会参与请求处理并出现在 API 文档中。
通过自定义注解忽略参数
- 在 paramIgnoreChange 方法中，使用 @ParamIgnore 注解标记了 id 和 user 参数。
- 系统会根据配置的 param.ignore[@com.example.springtest.anno.ParamIgnore]=true 规则，忽略这些参数，使其不参与请求处理且不出现在 API 文档中。

适用场景

隐藏敏感参数：忽略某些敏感参数（如内部标识符），避免其出现在 API 文档中。
排除无用参数：忽略某些不参与实际逻辑处理的参数，简化 API 请求和文档。
灵活控制参数可见性：根据业务需求，动态选择需要忽略的参数。

导出结果

在这里插入图片描述

2.5 API 配置：`param.required` 规则详解

功能描述
param.required 用于标记 API 参数是否为必填项。通过该规则，您可以从自定义注解（如 @ParamRequest）中提取参数是否为必填的信息，确保 API 调用时必填参数的校验逻辑正确。

配置方法

在配置文件中，您可以通过以下方式定义 param.required 规则：

从自定义注解中标记必填参数

param.required[@com.example.springtest.anno.ParamRequest]=true

默认行为
如果未配置 param.required 规则，系统会默认将参数标记为非必填。

使用示例

以下是一个完整的代码示例，展示了如何在 Java 中使用 param.required 规则：

package com.example.springtest.controller;

import com.example.springtest.anno.ParamRequest;
import com.example.springtest.entity.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/paramRequestController")
public class ParamRequestController {

    @GetMapping("/paramRequestControllerNoChange")
    public String paramRequestControllerNoChange(String id, String sex) {
        return "paramRequestControllerNoChange";
    }

    @GetMapping("/paramRequestControllerChange")
    public String paramRequestControllerChange(@ParamRequest String id, String sex) {
        return "paramRequestControllerChange";
    }
}

示例解析

默认行为
- 在 paramRequestControllerNoChange 方法中，未使用 @ParamRequest 注解，因此所有参数（id、sex）都会被标记为非必填。
通过自定义注解标记必填参数
- 在 paramRequestControllerChange 方法中，使用 @ParamRequest 注解标记了 id 参数。
- 系统会根据配置的 param.required[@com.example.springtest.anno.ParamRequest]=true 规则，将这些参数标记为必填项。

适用场景

必填参数校验：确保 API 调用时必填参数的正确性，避免因参数缺失导致的逻辑错误。
统一参数校验规范：在团队协作中，确保 API 参数的必填规则一致，提升代码可读性和维护性。
灵活控制参数必填性：根据业务需求，动态选择需要标记为必填的参数。

导出结果

在这里插入图片描述

3. 数据模型字段（Field）相关规则

3.1 API 配置：`field.schema.permit.null` 规则详解

功能描述
field.schema.permit.null 用于设置数据模型字段是否允许为 null。默认情况下，字段不允许为 null。通过该规则，您可以从自定义注解（如 @Null）中提取字段是否允许为 null 的信息，确保数据模型的校验逻辑符合业务需求。

配置方法

在配置文件中，您可以通过以下方式定义 field.schema.permit.null 规则：

从自定义注解中标记字段允许为 null

field.schema.permit.null=@com.example.springtest.anno.Null

默认行为
如果未配置 field.schema.permit.null 规则，系统会默认将字段标记为不允许为 null。

3.2 API 配置：`field.defaultValue` 规则详解

功能描述
field.defaultValue 用于设置数据模型字段的默认值。通过该规则，您可以从注释标签（如 #default）或自定义注解（如 @DefaultValueAnno）中提取字段的默认值，确保数据模型在未显式赋值时使用预设的默认值。

配置方法

在配置文件中，您可以通过以下方式定义 field.defaultValue 规则：

从注释标签中提取默认值
```
field.defaultValue=#default
```

从自定义注解中提取默认值

field.defaultValue[@com.example.springtest.anno.DefaultValueAnno]=@com.example.springtest.anno.DefaultValueAnno#value

默认行为
如果未配置 field.defaultValue 规则，系统不会为字段设置默认值。

由于篇幅问题这里就一把梭了。所有关于数据模型的规则全部在这个java代码里面


field.defaultValue=#default
field.example=#example
field.description=#fieldDesc
field.ignore=#fieldIgnore
field.ignore=ignoreLog
field.mock=#mock
float_with_two=@natural(0,10000).@natural(0,100)
field.name=#fieldName
field.required=#fieldRequire
#constant.field.ignore=XXID
field.schema.title=#chineseName
field.schema.min.length=#minLength
field.schema.max.length=#maxLength
field.schema.format=#format
field.schema.pattern=#pattern
field.schema.const=#const
field.schema.read.only=#readOnly
field.schema.write.only=#writeOnly
field.schema.permit.null=#null
field.order[@com.example.springtest.anno.Order]=@com.example.springtest.anno.Order#value
field.defaultValue[@com.example.springtest.anno.DefaultValueAnno]=@com.example.springtest.anno.DefaultValueAnno#value
field.example[@com.example.springtest.anno.Example]=@com.example.springtest.anno.Example#value
field.description[@com.example.springtest.anno.FieldDesc]=@com.example.springtest.anno.FieldDesc#value
field.ignore=@com.example.springtest.anno.FieldIgnore#value
field.mock=@com.example.springtest.anno.Mock#value
field.name=@com.example.springtest.anno.FieldName#value
field.required=@com.example.springtest.anno.FieldRequire#value
field.schema.title=@com.example.springtest.anno.ChineseName#value
field.schema.min.length=@com.example.springtest.anno.MinLength#value
field.schema.max.length=@com.example.springtest.anno.MaxLength#value
field.schema.format=@com.example.springtest.anno.Format#value
field.schema.pattern=@com.example.springtest.anno.Pattern#value
field.schema.const=@com.example.springtest.anno.Const#value
field.schema.read.only=@com.example.springtest.anno.ReadOnly#value
field.schema.write.only=@com.example.springtest.anno.WriteOnly#value
field.schema.permit.null=@com.example.springtest.anno.Null

package com.example.springtest.entity;

import com.example.springtest.anno.*;
import com.example.springtest.enumData.EnumData;
import com.example.springtest.enumData.UserTypeConstant;
import jakarta.annotation.Nullable;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;
import java.util.List;

/**
 * 描述有问题
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
public class FieldDefaultDto<T> implements Serializable {

    private List<T> data;

    private Object obj;

    private static final long serialVersionUID = -4607862808303533196L;


    private String price;//价格
    private String name;//名字
    private Integer age;//年龄

    /**
     * @default 100
     */
    private Integer ageAnno;

    @DefaultValueAnno("999")
    private Integer ageDoc;

    /**
     * @example 90
     */
    private Integer exampleAgeAnno;

    @Example("101")
    private Integer exampleAgeDoc;

    /**
     * 描述2
     *
     * @fieldDesc 描述一
     */
    private String descAnno;

    /**
     * 直接描述
     *
     * @fieldDesc 注释描述
     */
    @FieldDesc("注解描述")
    private String descDoc;

    private String ignoreNoField;

    /**
     * @fieldIgnore true
     */
    private String ignoreFieldAnno;

    @FieldIgnore(value = true)
    private String ignoreFieldDoc;

    private String log;
    private String ignoreLog;


    private String noMock;

    /**
     * @mock 1@natural(0,9)
     */
    private String mockDoc;

    @Mock("1@natural(0,10)")
    private String mockAnno;

    /**
     * @mock ${float_with_two}
     */
    private String mockDoc$;

    @Mock("${float_with_two}")
    private String mockAnno$;

    private String fieldName;

    /**
     * @fieldName fieldNameDoc
     */
    private String fieldNameD;

    @FieldName("fieldNameAnno")
    private String fieldNameA;

    private String fieldNoRequire;

    /**
     * @fieldRequire true
     */
    private String fieldRequireDoc;

    @FieldRequire(value = true)
    private String fieldRequireAnno;

    private UserTypeConstant userTypeConstant;

    /**
     * @see UserTypeConstant
     */
    private String userTypeConstantString;

    private String noChineseName;

    /**
     * @chineseName 注释中文名
     */
    private String chineseNameDoc;

    @ChineseName("注解中文名")
    private String chineseNameAnno;


    private String noMaxLength;

    /**
     * @maxLength 10
     */
    private String maxLengthDoc;

    @MaxLength("20")
    private String maxLengthAnno;

    private String noMinLength;

    /**
     * @minLength 10
     */
    private String minLengthDoc;

    @MinLength("20")
    private String minLengthAnno;

    private Integer noFormat;

    /**
     * @format long
     */
    private Integer formatDoc;

    @Format("long")
    private Integer formatAnno;

    private String noPattern;

    /**
     * @pattern ^\d{3}$
     */
    private String patternDoc;

    @Pattern("^\\d{4}$")
    private String patternAnno;

    private String noConst;

    /**
     * @const testDoc
     */
    private String constDoc;

    @Const("testAnno")
    private String constAnno;

    private String noReadOnly;

    /**
     * @readOnly
     */
    private String readOnlyDoc;

    @ReadOnly
    private String readOnlyAnno;


    private String noWriteOnly;

    /**
     * @writeOnly
     */
    private String writeOnlyDoc;

    @WriteOnly
    private String writeOnlyAnno;

    private String permitNull;

    /**
     * @null
     */
    private String permitNullDoc;

    @Null
    private Integer permitNullAnno;


    /**
     * @see EnumData#getAddress()
     */
    private String enumDataString;


    /**
     * @see EnumData#address
     */
    private String enumDataInteger;

    /**
     * @see EnumData
     */
    private EnumData enumDataSee;

    private EnumData address;

    private OpenDateEnum openDateEnum;


//    /**
//     * @writeOnly
//     */
//    private Case writeOnly;

    /**
     * @readOnly
     */
    private Case readOnly;


    /**
     * @fieldDoc 字段描述
     */
    private String fieldDoc;

    /**
     * @fieldDoc 字段描述数组
     */
    private List<String> fieldDocList;

    /**
     * 对象描述1
     *
     * @chineseName 注释中文名1
     */
    @FieldRequire
    @Null
    private FieldOrder desc1;

    /**
     * 对象描述2
     *
     * @chineseName 注释中文名2
     */
    @FieldIgnore
    private FieldOrder desc2;

    /**
     * 对象描述3
     *
     * @chineseName 注释中文名3
     */
    @FieldName("desc4")
    private FieldOrder desc3;

    @FieldRequire
    @Nullable
    private FieldOrder desc5;

    @FieldRequire
    @org.springframework.lang.Nullable
    private FieldOrder desc6;

    public String getPrice() {
        return price;
    }
}

package com.example.springtest.controller;

import com.example.springtest.entity.Case;
import com.example.springtest.entity.FieldDefaultDto;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping(value = "/fieldDefaultValueController")
public class FieldDefaultValueController {


    @PostMapping("/fieldDefaultValue")
    public String fieldDefaultValue(@RequestBody List<FieldDefaultDto<Case>> fieldDefaultDto){
        return "fieldDefaultValueController";
    }

    @PostMapping("/fieldExampleValue")
    public String fieldExampleValue(FieldDefaultDto fieldDefaultDto){
        return "fieldExampleValue";
    }

    @GetMapping("/fieldExampleValueGet")
    public String fieldExampleValueGet(FieldDefaultDto fieldDefaultDto){
        return "fieldExampleValue";
    }

    @GetMapping("/fieldDefaultValueGet")
    public String fieldDefaultValueGet(@RequestBody FieldDefaultDto fieldDefaultDto){
        return "fieldDefaultValueController";
    }

    @GetMapping("/fieldDefaultValueGetRead")
    public FieldDefaultDto fieldDefaultValueGetRead(@RequestBody FieldDefaultDto fieldDefaultDto){
        return null;
    }

}

导出结果

在这里插入图片描述

总结

Apifox Helper 的自定义规则功能，赋予开发者极高的灵活性，能够根据项目需求定制 API 文档生成规则。通过简单的配置，即可实现：

统一规范：团队协作中强制统一命名、格式、校验规则。
复杂场景适配：处理多路径、动态参数、泛型返回值等特殊场景。
文档增强：自动生成详细参数说明、Mock 数据、状态标记，提升文档质量。
高效维护：减少手动维护成本，通过注解和脚本动态生成内容。

Apifox Helper 的自定义规则如同乐高积木，开发者可通过灵活组合实现高度定制化的 API 文档管理。无论是统一团队规范，还是适配复杂业务逻辑，这一功能都能显著提升开发效率与文档质量。掌握本文核心规则后，结合官方文档探索更多可能性，将使您的 API 工程化水平更上一层楼！

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

引言

1. 方法（Method）相关规则

1.1 API 配置：api.name 规则详解

配置方法

使用示例

示例解析

适用场景

导出结果

1.2 API 配置：api.tags 规则详解

配置方法

使用示例

示例解析

适用场景

导出结果

1.3 API 配置：api.status 规则详解

配置方法

使用示例

示例解析

适用场景

导出结果

1.4 API 配置：method.description 规则详解

配置方法

使用示例

示例解析

适用场景

导出结果

1.5 API 配置：method.defaultContentType 规则详解

配置方法

使用示例

示例解析

适用场景

导出结果

1.6 API 配置：method.request.replace 规则详解

配置方法

使用示例

示例解析

适用场景

导出结果

1.7 API 配置：method.response.replace 规则详解

1.8 API 配置：method.additional.header 规则详解

配置方法

使用示例

示例解析

适用场景

导出结果

1.9 API 配置：method.additional.param 规则详解

1.10 API 配置：method.return 规则详解

配置方法

使用示例

示例解析

适用场景

导出结果

1.11 API 配置：method.return.body.type 规则详解

配置方法

使用示例

示例解析

适用场景

导出结果

1.12 API 配置：path.multi 规则详解

配置方法

使用示例

示例解析

适用场景

导出结果

2. 参数（Parameter）相关规则

2.1 API 配置：param.defaultValue 规则详解

配置方法

使用示例

示例解析

适用场景

导出结果

2.2 API 配置：param.description 规则详解

配置方法

使用示例

示例解析

适用场景

导出结果

2.3 API 配置：param.type 规则详解

配置方法

1.1 API 配置：`api.name` 规则详解

1.2 API 配置：`api.tags` 规则详解

1.3 API 配置：`api.status` 规则详解

1.4 API 配置：`method.description` 规则详解

1.5 API 配置：`method.defaultContentType` 规则详解

1.6 API 配置：`method.request.replace` 规则详解

1.7 API 配置：`method.response.replace` 规则详解

1.8 API 配置：`method.additional.header` 规则详解

1.9 API 配置：`method.additional.param` 规则详解

1.10 API 配置：`method.return` 规则详解

1.11 API 配置：`method.return.body.type` 规则详解

1.12 API 配置：`path.multi` 规则详解

2.1 API 配置：`param.defaultValue` 规则详解

2.2 API 配置：`param.description` 规则详解

2.3 API 配置：`param.type` 规则详解

2.4 API 配置：`param.ignore` 规则详解

2.5 API 配置：`param.required` 规则详解

3.1 API 配置：`field.schema.permit.null` 规则详解

3.2 API 配置：`field.defaultValue` 规则详解