SpringBoot从Swagger2迁移OpenApi3后Swagger UI 404问题求助

针对你遇到的v3接口文档可访问但Swagger UI 404的情况，结合你的场景（同流程其他项目正常、偶然成功重启后失效），可以从以下几个方向排查：

1. 验证上下文路径与SpringDoc配置匹配 #

你的Swagger UI路径包含/abc上下文，需确保SpringDoc配置正确适配该路径：

• 在application.properties/application.yml中添加配置：

  springdoc.swagger-ui.path=/abc/swagger-ui/index.html
  springdoc.api-docs.path=/abc/v3/api-docs
  

  或者统一配置base-path：

  springdoc.swagger-ui.base-path=/abc
  springdoc.api-docs.base-path=/abc
  

  避免因上下文路径导致静态资源映射错位。

2. 排查自定义拦截器对静态资源的拦截 #

除了Spring Security，项目中若存在自定义HandlerInterceptor或Filter，可能拦截了Swagger UI的静态资源：

• 确保自定义拦截器排除以下路径：

  @Override
  public void addInterceptors(InterceptorRegistry registry) {
      registry.addInterceptor(yourCustomInterceptor)
              .excludePathPatterns("/swagger-ui/**", "/webjars/**", "/v3/api-docs/**", "/abc/swagger-ui/**", "/abc/webjars/**");
  }
  

  这些路径包含Swagger UI依赖的静态资源（webjars下的swagger-ui相关文件）。

3. 确认SpringBoot与SpringDoc版本兼容性 #

springdoc-openapi-ui 1.6.11适配SpringBoot 2.4.x~2.6.x版本，若当前项目的SpringBoot版本不在此范围，可能出现资源加载异常：

• 检查pom.xml/build.gradle中的SpringBoot版本，若版本不匹配，要么调整SpringBoot版本，要么升级springdoc到对应兼容版本（比如SpringBoot 2.7+对应springdoc 1.7.x+）。

4. 清理项目缓存与重新构建 #

偶然成功后重启失效，可能是类加载或静态资源缓存问题：

• 手动删除项目的target/build目录，执行mvn clean install（Maven）或gradle clean build（Gradle）重新构建；
• 启动时添加JVM参数禁用缓存：-Dspring.resources.chain.cache=false，避免静态资源被缓存导致加载失败。

5. 检查旧配置残留与冲突 #

确认项目中已完全移除Swagger2相关依赖与配置：

• 删除旧的springfox-swagger2、springfox-swagger-ui依赖；
• 检查是否存在未删除的Swagger2配置类（如@EnableSwagger2注解的类），这类配置会与SpringDoc产生冲突。

6. 验证Spring Security拦截规则 #

虽然你已配置忽略相关路径，但需确保规则覆盖完整：

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
            .antMatchers("/v3/api-docs/**", "/swagger-ui/**", "/webjars/**", "/abc/swagger-ui/**", "/abc/v3/api-docs/**")
            .permitAll()
            .anyRequest().authenticated();
}

注意包含上下文路径的完整路径，避免因路径匹配不全导致拦截。

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