如何配置springdoc-openapi-starter-webflux-ui为受保护资源启用Bearer授权

核心问题原因 #

Springdoc不会自动探测JWT安全配置，需要显式定义OpenAPI的安全方案（SecurityScheme），才能在Swagger UI中生成授权入口。

步骤1：添加OpenAPI安全配置类 #

创建配置类，指定Bearer Token认证类型，并全局启用该安全要求：

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        final String securitySchemeName = "bearerAuth";
        return new OpenAPI()
                // 全局添加安全要求，所有受保护接口都会关联该认证
                .addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
                .components(new Components()
                        .addSecuritySchemes(securitySchemeName, new SecurityScheme()
                                .name(securitySchemeName)
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")
                                .bearerFormat("JWT") // 指定令牌格式为JWT，可选但建议添加
                        )
                );
    }
}

步骤2：确认Spring Security放行Swagger路径 #

确保你的SecurityWebFilterChain配置中，已放行Swagger的所有相关路径（避免授权按钮无法加载）：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.web.server.ServerHttpSecurity;
import org.springframework.security.web.server.SecurityWebFilterChain;

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
        return http
                .authorizeExchange(exchanges -> exchanges
                        // 放行Swagger文档相关路径
                        .pathMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html").permitAll()
                        // 放行公开API
                        .pathMatchers("/auth/register", "/auth/login").permitAll()
                        // 其余路径需认证
                        .anyExchange().authenticated()
                )
                .csrf(ServerHttpSecurity.CsrfSpec::disable)
                // 挂载你的JWT过滤器
                .addFilterAt(jwtAuthenticationFilter(), SecurityWebFiltersOrder.AUTHENTICATION)
                .build();
    }

    // 替换为你实际的JWT过滤器实现
    private JwtAuthenticationFilter jwtAuthenticationFilter() {
        return new JwtAuthenticationFilter();
    }
}

步骤3：验证依赖版本兼容性 #

确保springdoc-openapi-starter-webflux-ui版本与Spring Boot版本匹配：

• Spring Boot 3.x → 使用2.x版本的springdoc starter
• Spring Boot 2.x → 使用1.x版本的springdoc starter

示例Maven依赖（Spring Boot 3.x）：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.2.0</version>
</dependency>

验证效果 #

启动应用后访问/swagger-ui.html，右上角会出现Authorize按钮。点击后输入Bearer {你的JWT令牌}（注意Bearer后加空格），保存后即可访问受保护的查询用户API。

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