OpenApi 3.0.1中如何配置枚举展示自定义属性而非默认枚举名

以下针对你使用的不同Swagger版本提供对应实现方案： #

方案1：Springdoc OpenAPI 3.x（SpringBoot 2.x/3.x主流版本） #

通过自定义全局枚举转换器，自动适配ErrorCode枚举的展示逻辑：

1. 首先创建自定义Model转换器

import io.swagger.v3.core.converter.AnnotatedType;
import io.swagger.v3.core.converter.ModelConverter;
import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.oas.models.media.IntegerSchema;
import io.swagger.v3.oas.models.media.Schema;
import java.util.Arrays;
import java.util.Iterator;
import java.util.stream.Collectors;

public class ErrorCodeEnumConverter implements ModelConverter {
    @Override
    public Schema resolve(AnnotatedType type, ModelConverterContext context, Iterator<ModelConverter> chain) {
        // 仅处理ErrorCode类型的字段
        if (type.getType().getTypeName().equals(ErrorCode.class.getName())) {
            IntegerSchema schema = new IntegerSchema();
            // 自动提取所有枚举项的errorId作为允许值
            schema.setAllowableValues(Arrays.stream(ErrorCode.values())
                    .map(ErrorCode::getErrorId)
                    .collect(Collectors.toList()));
            // 可选：补充每个错误码对应的说明
            String desc = Arrays.stream(ErrorCode.values())
                    .map(e -> e.getErrorId() + ": " + e.getErrorMsg())
                    .collect(Collectors.joining("<br/>"));
            schema.setDescription("错误码列表：<br/>" + desc);
            return schema;
        }
        return chain.next().resolve(type, context, chain);
    }
}

2. 注册转换器到Swagger配置

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public ModelConverter errorCodeEnumConverter() {
        return new ErrorCodeEnumConverter();
    }
}

配置完成后所有标注@Schema(implementation = ErrorCode.class)的字段会自动展示为整数类型，可选值为所有枚举的errorId，同时附带每个错误码的说明。 #

方案2：Springfox Swagger 2.x 旧版本 #

自定义属性构建插件实现：

import com.fasterxml.classmate.ResolvedType;
import com.google.common.base.Optional;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ModelPropertyBuilder;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.schema.ModelPropertyBuilderPlugin;
import springfox.documentation.spi.schema.contexts.ModelPropertyContext;
import java.util.Arrays;
import java.util.stream.Collectors;

@Component
public class ErrorCodeEnumPlugin implements ModelPropertyBuilderPlugin {
    @Override
    public void apply(ModelPropertyContext context) {
        Optional<ResolvedType> resolvedType = context.getResolvedType();
        if (resolvedType.isPresent() && resolvedType.get().getErasedType() == ErrorCode.class) {
            ModelPropertyBuilder builder = context.getBuilder();
            // 设置允许值为所有errorId
            builder.allowableValues(Arrays.stream(ErrorCode.values())
                    .map(ErrorCode::getErrorId)
                    .collect(Collectors.toList()));
            // 补充错误码说明
            String desc = Arrays.stream(ErrorCode.values())
                    .map(e -> e.getErrorId() + ": " + e.getErrorMsg())
                    .collect(Collectors.joining("\n"));
            builder.description("错误码说明：\n" + desc);
            // 字段类型设置为整数
            builder.type(Integer.class);
        }
    }

    @Override
    public boolean supports(DocumentationType delimiter) {
        return DocumentationType.SWAGGER_2 == delimiter;
    }
}

轻量临时方案（无需全局配置） #

直接在ErrorCode枚举类上通过@Schema注解硬编码允许值，适合枚举项少且变更频率低的场景：

@Getter
@Schema(description = "错误码枚举", allowableValues = {"100001", "100002", "300003"})
public enum ErrorCode implements BaseError {
    // 原有枚举项保持不变
}

内容的提问来源于stack exchange，提问作者du-it