枚举展示插件

枚举展示插件用于在 API 文档中增强枚举类型的展示效果，自动解析枚举的 value-description 映射关系。

UI 适配效果

配置插件后，UI 会在接口详情与在线调试中增强枚举展示，直接呈现枚举值与说明信息：

▲ 接口详情中的枚举值与说明展示

▲ 在线调试时可下拉选择枚举值

快速开始

1. 引入依赖

Spring Boot 3

<dependency>
    <groupId>top.nextdoc4j</groupId>
    <artifactId>nextdoc4j-plugin-enum-springboot3</artifactId>
</dependency>

Spring Boot 4

<dependency>
    <groupId>top.nextdoc4j</groupId>
    <artifactId>nextdoc4j-plugin-enum-springboot4</artifactId>
</dependency>

建议先在 dependencyManagement 中引入 nextdoc4j-bom-springboot3/4，这样这里无需单独写版本号。

2. 启用插件

nextdoc4j:
  plugin:
    enum:
      enabled: true

3. 定义枚举

实现 EnumValue<T> 接口：

@Getter
@RequiredArgsConstructor
public enum OrderStatus implements EnumValue<String> {

    PENDING("PENDING", "待支付"),
    PAID("PAID", "已支付"),
    SHIPPED("SHIPPED", "已发货"),
    COMPLETED("COMPLETED", "已完成"),
    CANCELLED("CANCELLED", "已取消");

    private final String value;
    private final String description;
}

模块说明

类	说明
EnumValue<T>	枚举值接口，定义 getValue() 和 getDescription()
DefaultEnumMetadataResolver	默认解析器，处理 EnumValue 接口枚举
EnumMetadataResolver	自定义解析器接口

支持的类型

Java 类型	OpenAPI Type	OpenAPI Format
Integer / int	integer	int32
Long / long	integer	int64
String	string	-
Double / double	number	double
Float / float	number	double

自定义解析器

如需支持其他枚举接口，实现 EnumMetadataResolver：

@Component
public class BusinessEnumResolver implements EnumMetadataResolver {

    @Override
    public boolean supports(Class<?> enumClass) {
        return enumClass != null
            && enumClass.isEnum()
            && BusinessEnum.class.isAssignableFrom(enumClass);
    }

    @Override
    public Class<?> getEnumInterfaceType() {
      return BusinessEnum.class;
    }

    @Override
    public String getValueMethodName() {
        return "getCode";
    }

    @Override
    public String getDescriptionMethodName() {
        return "getLabel";
    }
}

OpenAPI 输出效果

{
  "status": {
    "type": "string",
    "enum": ["PENDING", "PAID", "SHIPPED", "COMPLETED", "CANCELLED"],
    "x-nextdoc4j-enum": {
      "items": [
        { "value": "PENDING", "description": "待支付" },
        { "value": "PAID", "description": "已支付" },
        { "value": "SHIPPED", "description": "已发货" },
        { "value": "COMPLETED", "description": "已完成" },
        { "value": "CANCELLED", "description": "已取消" }
      ]
    }
  }
}

NextDoc4j UI 会读取 x-nextdoc4j-enum 扩展字段，在调试时下拉展示枚举值及其描述。