Spring Boot项目Swagger3-ui无法访问问题排查（附配置与依赖）

已知前置条件 #

• 尝试访问常规Swagger UI地址均返回资源加载失败、404错误：
  • http://localhost:8080/swagger-ui/index.html
  • http://localhost:8080/swagger-ui/
• 项目中Springfox配置类语法无报错，包扫描、路径匹配规则的基础配置逻辑正常
• pom.xml已正确引入springfox-boot-starter 3.0.0依赖

常见根因与修复方案 #

Spring Boot高版本兼容冲突 #

Springfox 3.0.0 原生适配Spring Boot 2.5及以下版本，当项目使用Spring Boot 2.6以上版本时，框架默认启用新的PathPatternParser路径匹配策略，会直接拦截Springfox注册的文档接口、UI静态资源，导致访问失败。
修复操作：

1. 在项目配置文件（application.properties/application.yml）中追加配置，切回旧版Ant风格路径匹配策略：

   spring.mvc.pathmatch.matching-strategy=ant_path_matcher
   

提示：Springfox 3.0.0已停止维护，完全不兼容Spring Boot 3的jakarta包迁移规范，遇到Spring Boot 3版本集成需求需直接更换为springdoc-openapi依赖，无需继续排查Springfox相关配置

拦截规则未放行Swagger相关路径 #

如果项目接入了Spring Security、自定义登录拦截器，默认拦截规则会拦截所有未配置白名单的路径，Swagger的文档接口、静态资源不在白名单内时，会被拦截返回401、404错误。
需要在拦截配置的白名单中追加以下路径：

• /swagger-ui/**
• /swagger-resources/**
• /v2/api-docs
• /v3/api-docs
• /webjars/**
  自定义拦截器配置示例：

@Configuration
public class AuthInterceptorConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new LoginAuthInterceptor())
                .excludePathPatterns(
                    "/swagger-ui/**",
                    "/swagger-resources/**",
                    "/v2/api-docs",
                    "/v3/api-docs",
                    "/webjars/**"
                );
    }
}

缺失OpenApi触发注解 #

Springfox 3.0.0 废弃了原2.x版本的@EnableSwagger2注解，需要在Swagger配置类上添加@EnableOpenApi注解，才能触发文档扫描逻辑，否则Docket Bean不会被加载，文档接口无任何返回。
修复方式：
在现有SpringFoxConfig类上补充注解，原有Docket Bean配置逻辑保持不变：

@Configuration
@EnableOpenApi
public class SpringFoxConfig {
    @Bean
    public Docket apiDocket() {
        // 原有配置逻辑
    }
}

静态资源映射规则缺失 #

如果项目自定义了WebMvc的静态资源映射规则，覆盖了Spring Boot默认的静态资源加载逻辑，会导致Swagger UI的静态资源无法被读取。
需要在自定义的资源映射配置中补充Swagger UI的资源路径映射：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    // 原有项目静态资源映射逻辑
    registry.addResourceHandler("/swagger-ui/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
}

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