Spring Boot 3集成springdoc-openapi-ui遇Swagger UI 403错误求助

问题场景 #

使用springdoc-openapi-ui进行API文档管理，Spring Boot父版本为3，访问http://localhost:8080/swagger-ui.html时出现403错误。已尝试将Swagger URL加入白名单、修改Swagger文档路径，但问题仍未解决，控制台无异常日志，请求直接被拒绝。

依赖配置 #

<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-ui</artifactId>
   <version>1.6.14</version>
</dependency>

Spring Boot Security配置 #

public static String[] SWAGGER_WHITELIST = {
        "/api-docs",
        "/swagger-ui.html",
        "/swagger-resources/**",
        "/webjars/**",
        "/swagger.json"
};

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http.cors().disable();
    http.csrf().disable();

    http.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);

    http
        .authorizeHttpRequests()
            .requestMatchers(SWAGGER_WHITELIST).permitAll()
            .requestMatchers(AUTH_WHITELIST).permitAll()

    .and()
        .addFilterAt(new JWTAuthenticationFilter(userService, jwtService, authenticationProvider()), UsernamePasswordAuthenticationFilter.class)
//        .addFilterAfter(new UserAuthorizationFilter(), JWTAuthenticationFilter.class)
        .authorizeHttpRequests()
            .anyRequest().authenticated();

    return http.build();
}

可能的原因及解决方法 #

1. springdoc版本与Spring Boot 3不兼容 #

Spring Boot 3基于Jakarta EE规范，而springdoc-openapi-ui:1.6.14是适配Spring Boot 2.x（基于javax）的版本，两者底层依赖存在冲突，会导致Swagger的路径映射、资源加载异常，进而被Security拦截。

解决方法：
升级到适配Spring Boot 3的springdoc v2.x版本，注意artifactId已变更：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version> <!-- 可替换为最新稳定版 -->
</dependency>

2. Swagger白名单路径不全（适配v2.x版本） #

springdoc v2.x针对Spring Boot 3调整了默认路径，旧的白名单路径无法覆盖新的Swagger资源请求：

• 原/api-docs变更为/v3/api-docs/**
• 新增/swagger-ui/**用于加载UI静态资源

解决方法：更新白名单数组：

public static String[] SWAGGER_WHITELIST = {
    "/v3/api-docs/**",
    "/swagger-ui/**",
    "/swagger-ui.html",
    "/webjars/**"
};

3. Spring Security配置语法问题 #

Spring Security 6（Spring Boot 3默认版本）的链式调用逻辑有调整，多次调用authorizeHttpRequests()可能导致权限规则优先级混乱，之前配置的permitAll规则可能被后续的anyRequest().authenticated()覆盖。

解决方法：合并权限配置逻辑，确保规则顺序正确：

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http.cors().disable()
        .csrf().disable()
        .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
        .and()
        .authorizeHttpRequests(auth -> auth
                .requestMatchers(SWAGGER_WHITELIST).permitAll()
                .requestMatchers(AUTH_WHITELIST).permitAll()
                .anyRequest().authenticated()
        )
        .addFilterAt(new JWTAuthenticationFilter(userService, jwtService, authenticationProvider()), UsernamePasswordAuthenticationFilter.class);

    return http.build();
}

4. 额外检查项 #

• 确认AUTH_WHITELIST中没有包含会冲突的路径规则
• 检查是否存在其他自定义过滤器或拦截器在Spring Security之前拦截请求

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