Spring Webflux+OpenAPI3：Swagger UI参数配置问题咨询

1. 修复required参数的Swagger UI缺失提示问题 #

Webflux RouterFunction模式下，仅设置required=true无法被springdoc正确识别，需显式声明参数必填性：

方式一：Handler方法注解声明 #

在Handler的参数上添加@Parameter注解明确必填属性：

public Mono<ServerResponse> getById(
        @Parameter(required = true, description = "资源ID") @PathVariable String id,
        @Parameter(required = true, description = "授权令牌") @RequestHeader("Authorization") String authToken,
        ServerRequest request) {
    // 业务逻辑实现
}

方式二：RouterFunction中显式配置 #

通过withParameter方法直接在路由里定义参数规则：

@Bean
public RouterFunction<ServerResponse> userRoutes(UserHandler handler) {
    return RouterFunctions.route()
            .GET("/users/{id}", request -> handler.getById(
                    request.pathVariable("id"),
                    request.headers().firstHeader("Authorization"),
                    request))
            .withParameter("id", param -> param.required(true).description("资源ID"))
            .withParameter("Authorization", param -> param.required(true).description("授权令牌").in(ParameterIn.HEADER))
            .build();
}

同时确保springdoc配置类启用Webflux支持：

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("响应式API文档").version("v1"));
    }

    @Bean
    public RouterFunction<ServerResponse> springDocRouterFunction(OpenApiResource openApiResource) {
        return RouterFunctions.route(GET("/v3/api-docs"), openApiResource::openapi);
    }
}

2. 为id参数添加正则校验及提示 #

通过@Parameter的schema属性指定正则规则，同时补充描述说明校验要求：

Handler注解方式 #

public Mono<ServerResponse> getById(
        @Parameter(
                required = true,
                description = "资源ID，格式要求：5-15位字母或数字",
                schema = @Schema(pattern = "^[a-zA-Z0-9]{5,15}$", example = "abc123")
        ) @PathVariable String id,
        ServerRequest request) {
    // 业务逻辑实现
}

Router配置方式 #

@Bean
public RouterFunction<ServerResponse> userRoutes(UserHandler handler) {
    Schema schema = new Schema()
            .pattern("^[a-zA-Z0-9]{5,15}$")
            .description("资源ID，格式要求：5-15位字母或数字")
            .example("abc123");

    return RouterFunctions.route()
            .GET("/users/{id}", request -> handler.getById(request.pathVariable("id"), request))
            .withParameter("id", param -> param.required(true).schema(schema))
            .build();
}

若需后端校验，可结合@Pattern注解：

public Mono<ServerResponse> getById(
        @Parameter(required = true)
        @Pattern(regexp = "^[a-zA-Z0-9]{5,15}$", message = "ID格式错误，需为5-15位字母或数字")
        @PathVariable String id,
        ServerRequest request) {
    // 校验逻辑或使用Validator处理
}

3. 为参数添加枚举实现Swagger UI下拉框 #

先定义枚举类：

public enum UserStatus {
    ACTIVE("激活"),
    INACTIVE("禁用"),
    PENDING("待审核");

    private final String desc;

    UserStatus(String desc) {
        this.desc = desc;
    }

    public String getDesc() {
        return desc;
    }
}

方式一：直接使用枚举作为参数类型 #

Handler方法参数设为枚举类型，springdoc会自动生成下拉框：

public Mono<ServerResponse> getByStatus(
        @Parameter(required = true, description = "用户状态") @RequestParam UserStatus status,
        ServerRequest request) {
    // 业务逻辑实现
}

方式二：Router中显式绑定枚举 #

若参数为String类型，需在路由配置里指定schema的枚举实现：

@Bean
public RouterFunction<ServerResponse> userRoutes(UserHandler handler) {
    Schema schema = new Schema()
            .implementation(UserStatus.class)
            .description("用户状态");

    return RouterFunctions.route()
            .GET("/users/status", request -> handler.getByStatus(
                    UserStatus.valueOf(request.queryParam("status").get()),
                    request))
            .withParameter("status", param -> param.required(true).schema(schema))
            .build();
}

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