Spring Boot 3.1.5集成Springdoc后Swagger UI报404求助

问题场景 #

集成Springdoc OpenAPI时，/v3/api-docs可正常返回API JSON数据，但Swagger UI访问时出现404错误，控制台提示No mapping for GET /swagger-ui/index.html。

核心原因 #

你的SecurityConfiguration继承了WebMvcConfigurationSupport，这个操作会禁用Spring Boot的Spring MVC自动配置，包括Swagger UI所需的静态资源映射规则——即使在白名单中添加了/swagger-ui/**，也无法找到对应的静态文件。

解决方案 #

方案1：替换WebMvcConfigurationSupport为WebMvcConfigurer接口 #

这是最推荐的方式，既能自定义MVC配置，又不会覆盖自动配置：

修改SecurityConfiguration的继承关系：

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfiguration implements WebMvcConfigurer { // 改为实现WebMvcConfigurer
    private final JwtAuthenticationFilter jwtAuthFilter;
    private final AuthenticationProvider authenticationProvider;

    private static final String[] URL_WHITELIST = {
            ApplicationConstants.AUTH + "/**",
            ApplicationConstants.PARKING_SPOT + ID,
            "/error",
            "/favicon.ico",
            "/swagger-resources",
            "/swagger-resources/**",
            "/configuration/ui",
            "/configuration/security",
            "/swagger-ui.html",
            "/webjars/**",
            "/v3/api-docs/**",
            "/api/public/**",
            "/api/public/authenticate",
            "/actuator/*",
            "/swagger-ui/**"
    };

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
                .csrf(AbstractHttpConfigurer::disable)
                .authorizeHttpRequests(authorize -> authorize
                        .requestMatchers(URL_WHITELIST)
                        .permitAll()
                        .anyRequest()
                        .authenticated())
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .authenticationProvider(authenticationProvider)
                .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class);
        return http.build();
    }
}

方案2：若必须继承WebMvcConfigurationSupport，手动添加静态资源映射 #

如果业务需要必须继承WebMvcConfigurationSupport，重写addResourceHandlers方法添加Swagger UI的资源映射：

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfiguration extends WebMvcConfigurationSupport {
    private final JwtAuthenticationFilter jwtAuthFilter;
    private final AuthenticationProvider authenticationProvider;

    private static final String[] URL_WHITELIST = {
            // 原有白名单内容不变
    };

    // 添加静态资源映射
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/")
                .resourceChain(false);
        registry.addResourceHandler("/v3/api-docs/**")
                .addResourceLocations("classpath:/META-INF/resources/");
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        // 原有SecurityFilterChain配置不变
    }
}

额外优化：移除冗余依赖 #

springdoc-openapi-starter-webmvc-ui已经内置了swagger-annotations，不需要单独引入io.swagger.core.v3:swagger-annotations，移除该依赖避免版本冲突：

<!-- 移除这个冗余依赖 -->
<!--<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.2.18</version>
</dependency>-->

验证 #

修改完成后重启项目，访问/swagger-ui/（或直接/swagger-ui/index.html），Swagger UI应该能正常加载。

相关情况 #

不少使用Spring Boot 3.x + Springdoc 2.x版本的开发者都遇到过这个问题，核心原因都是WebMvcConfigurationSupport覆盖自动配置导致静态资源映射丢失。

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