Spring 6（非SpringBoot）迁移后Swagger UI 404问题求助

架构老林

2026-7-6

Spring 6迁移后Swagger UI 404问题排查与解决

可能的原因及修复步骤

1. 确认springdoc依赖版本适配Spring 6

Spring 6必须使用springdoc-openapi-starter-webmvc-ui 2.x及以上版本，检查你的依赖配置：

Maven示例：

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

Gradle示例：

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

注意：不要使用旧版的springdoc-openapi-ui包，Spring 6仅支持starter系列依赖

2. 放行Swagger UI静态资源

如果自定义了WebMvcConfigurer，可能拦截了Swagger的静态资源，需添加资源映射规则：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/v3/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/");
    }
}

3. 验证上下文路径匹配

如果应用配置了server.servlet.context-path，访问Swagger UI时必须带上该路径。比如上下文路径为/demo，则正确访问地址是localhost:1010/demo/v3/swagger-ui/index.html

4. 配置Spring Security放行规则（若使用）

如果集成了Spring Security，需在安全配置中放行Swagger相关路径：

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
                .requestMatchers("/v3/api-docs/**", "/v3/swagger-ui/**")
                .permitAll()
                .anyRequest()
                .authenticated()
        );
        return http.build();
    }
}