如何基于springdoc-openapi在Java不同控制器中隐藏枚举值

方式一：通过@Schema注解直接指定允许值（快速实现） #

针对单个接口或DTO字段，直接在枚举参数/字段上添加@Schema注解，明确指定允许展示的枚举值，Swagger UI会自动生成对应的下拉选项：

// 示例DTO
public class StageRequest {
    // 只展示Stage1、Stage2、Stage4，隐藏Stage3
    @Schema(allowableValues = {"Stage1", "Stage2", "Stage4"})
    private Stage stage;

    // getter/setter
}

// 控制器接口
@PostMapping("/api/stage")
public ResponseEntity<Void> submitStage(@RequestBody StageRequest request) {
    // 业务逻辑
    return ResponseEntity.ok().build();
}

这种方式不需要修改原有枚举类，仅针对需要隐藏值的场景单独配置，同时不影响其他接口对完整枚举的使用。

方式二：自定义SchemaFilter（全局批量配置） #

如果多个接口需要统一隐藏某个枚举值，可实现SchemaFilter接口来全局过滤枚举值：

import io.swagger.v3.oas.models.media.Schema;
import org.springdoc.core.customizers.SchemaFilter;

public class StageEnumFilter implements SchemaFilter {
    @Override
    public void filter(Schema schema, SchemaFilterContext context) {
        // 判断当前处理的是Stage枚举类
        if (context.getType().equals(Stage.class)) {
            // 移除需要隐藏的Stage3
            schema.getEnum().remove("Stage3");
        }
    }
}

然后在Spring配置类中注册这个过滤器：

import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenApiCustomiser openApiCustomiser() {
        return openApi -> openApi.getComponents().getSchemas().values().forEach(schema -> {
            new StageEnumFilter().filter(schema, null);
        });
    }
}

注意：如果需要针对特定接口生效，可在Filter中额外判断请求路径或控制器类信息。

修复你之前的DTO+自定义序列化方案 #

你之前的问题出在只做了序列化处理，但未同步配置Swagger的枚举元数据，需要同时配合@Schema注解指定允许值：

// 自定义序列化器（仅序列化允许的枚举值）
public class StageSerializer extends StdSerializer<Stage> {
    private static final Set<Stage> ALLOWED_STAGES = Set.of(Stage.Stage1, Stage.Stage2, Stage.Stage4);

    public StageSerializer() {
        super(Stage.class);
    }

    @Override
    public void serialize(Stage value, JsonGenerator gen, SerializerProvider provider) throws IOException {
        if (ALLOWED_STAGES.contains(value)) {
            gen.writeString(value.name());
        } else {
            // 可抛出异常或返回默认值，根据业务需求处理
            throw new IllegalArgumentException("Invalid stage value");
        }
    }
}

// DTO中同时配置序列化和Swagger注解
public class RestrictedStageRequest {
    @JsonSerialize(using = StageSerializer.class)
    @Schema(allowableValues = {"Stage1", "Stage2", "Stage4"})
    private Stage stage;

    // getter/setter
}

这样既保证了接口只接受允许的枚举值，也能让Swagger UI正确识别枚举类型并生成下拉选择器。

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