如何在SpringDoc OpenAPI的Swagger UI中对@PathVariable枚举值排序

由于枚举来自外部依赖无法修改定义顺序，可通过自定义Swagger的Schema处理器调整枚举选项的展示顺序，以下分两种主流Swagger实现给出方案：

方案一：基于SpringDoc OpenAPI（OpenAPI 3.x） #

1. 自定义EnumSchemaCustomizer实现SchemaCustomizer接口，对指定枚举的可选项排序：

import org.springdoc.core.customizers.SchemaCustomizer;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import io.swagger.v3.core.converter.AnnotatedType;
import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.oas.models.media.Schema;

import java.util.Comparator;
import java.util.List;
import java.util.stream.Collectors;

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class SortedEnumSchemaCustomizer implements SchemaCustomizer {

    @Override
    public void customize(Schema schema, AnnotatedType type, ModelConverterContext context) {
        // 替换为实际外部枚举类的全限定名
        if (type.getType() != null && type.getType().getTypeName().equals("com.external.dependency.StatusEnum")) {
            List<String> sortedEnumValues = schema.getEnum()
                    .stream()
                    .map(Object::toString)
                    .sorted(Comparator.naturalOrder())
                    .collect(Collectors.toList());
            schema.setEnum(sortedEnumValues);
        }
    }
}

2. 启动项目后，Swagger UI中该枚举的@PathVariable参数选项会自动按字母顺序排列。

方案二：基于SpringFox（Swagger 2.x） #

1. 自定义EnumModelPropertyBuilderPlugin实现ModelPropertyBuilderPlugin接口：

import com.fasterxml.classmate.TypeResolver;
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.Comparator;
import java.util.List;
import java.util.stream.Collectors;

@Component
public class SortedEnumModelPropertyPlugin implements ModelPropertyBuilderPlugin {

    private final TypeResolver typeResolver;

    public SortedEnumModelPropertyPlugin(TypeResolver typeResolver) {
        this.typeResolver = typeResolver;
    }

    @Override
    public void apply(ModelPropertyContext context) {
        Class<?> rawType = context.getBeanPropertyDefinition().getRawType();
        // 替换为实际外部枚举类
        if (rawType == com.external.dependency.StatusEnum.class) {
            ModelPropertyBuilder builder = context.getBuilder();
            List<String> sortedEnums = Arrays.stream(rawType.getEnumConstants())
                    .map(Enum::name)
                    .sorted(Comparator.naturalOrder())
                    .collect(Collectors.toList());
            builder.enumValues(sortedEnums);
        }
    }

    @Override
    public boolean supports(DocumentationType documentationType) {
        return true;
    }
}

2. 确保SpringFox配置类扫描到该自定义插件，重启项目后即可看到排序后的枚举选项。

关键说明 #

• 两种方案均拦截Swagger的Schema/ModelProperty构建流程，仅调整展示顺序，不影响枚举本身的业务逻辑。
• 需将代码中的枚举类路径替换为你实际使用的外部枚举全限定名。
• 若需对所有枚举生效，可移除类型判断条件，但建议仅针对目标枚举处理，避免影响其他接口。

内容的提问来源于stack exchange，提问作者beatarjn