Spring Boot 2.x升3.x(Java17)后WebFlux下Swagger UI异常排查

1. 核对Swagger UI访问路径 #

SpringDoc OpenAPI 2.x（适配Spring Boot 3）的默认访问路径已从/swagger-ui.html变更为/swagger-ui/index.html，旧路径会直接返回静态HTML源码。可直接访问新路径测试，或在配置类中添加重定向规则：

@Bean
public RouterFunction<ServerResponse> swaggerRedirectRouter() {
    return route(GET("/swagger-ui.html"), req ->
            ServerResponse.temporaryRedirect(URI.create("/swagger-ui/index.html")).build()
    );
}

2. 确认依赖兼容性与完整性 #

• 确保仅引入WebFlux专属的SpringDoc依赖，不要混合Servlet相关包，正确的依赖组合：

implementation 'org.springdoc:springdoc-openapi-starter-webflux-ui:2.5.0'
// 仅当需要手动扩展API模型时再引入api包，UI包已包含基础API依赖
// implementation 'org.springdoc:springdoc-openapi-starter-webflux-api:2.5.0'

• 检查Spring Boot与SpringDoc版本匹配：Spring Boot 3.2.x对应SpringDoc 2.5.x；3.1.x对应2.2.x；3.0.x对应2.0.x，版本不匹配会引发各类兼容问题。

3. 修复资源处理器冲突 #

若自定义的addResourceHandlers配置覆盖了默认静态资源映射，会导致Swagger UI的静态资源无法被解析。可移除自定义资源处理器，或修改为包含Swagger资源路径：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/swagger-ui/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/");
}

4. 校验OpenAPI Bean配置 #

确保OpenAPI Bean的元数据配置正确，错误的定义会导致UI无法加载API文档：

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info().title("WebFlux API 文档")
                    .version("1.0")
                    .description("基于Spring Boot 3的WebFlux接口文档"));
}

5. 排查全局过滤器/拦截器 #

项目中自定义的GlobalFilter或拦截器可能篡改响应内容，将Swagger动态请求误判为静态资源。可临时禁用所有自定义过滤器，测试是否恢复正常，再逐个排查冲突项。

6. 检查配置文件与权限 #

• 确认application配置中未禁用SpringDoc自动配置：

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true

• 若启用Spring Security，需放行Swagger相关路径：

@Bean
public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
    return http.authorizeExchange(exchanges -> exchanges
                    .pathMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
                    .anyExchange().authenticated()
            )
            .build();
}

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