Spring WebFlux应用无法访问Swagger UI的求助排查

WebFlux + springdoc-openapi-webflux-ui 1.6.13的默认访问路径 #

针对Spring Boot 2.7.5 + springdoc-openapi-webflux-ui 1.6.13组合，默认访问路径如下：

• Swagger UI页面：http://localhost:8080/swagger-ui.html
• WebJar形式的UI入口：http://localhost:8080/webjars/swagger-ui/index.html
• OpenAPI接口文档：http://localhost:8080/v3/api-docs

问题排查与修复步骤 #

从报错日志中org.springframework.web.servlet.PageNotFound可以看出，请求被Spring MVC的DispatcherServlet处理，而非WebFlux的DispatcherHandler，这是核心异常点，按以下步骤排查：

1. 检查依赖冲突
   确保项目POM中没有同时引入spring-boot-starter-web和spring-boot-starter-webflux。若两者共存，Spring Boot会自动切换为MVC模式，导致WebFlux配置失效。需移除spring-boot-starter-web依赖。

2. 禁用MVC模式强制启用
   检查主类或配置类，确保没有添加@EnableWebMvc注解。该注解会强制启用Spring MVC，覆盖WebFlux的自动配置。

3. 验证springdoc配置
   检查application.yml或application.properties中是否存在自定义路径配置：

   # 若有如下配置，需使用自定义路径访问
   springdoc.swagger-ui.path=/custom-swagger-ui.html
   springdoc.api-docs.path=/custom-api-docs
   

   若未自定义，保持默认配置即可。

4. 清理缓存并重新构建
   执行Maven命令清理构建缓存：

   mvn clean install
   

   避免旧编译文件或依赖缓存导致的异常。

5. 放行Swagger相关路由
   若自定义了WebFlux路由或添加了Spring Security，需确保放行以下路径：

   • /swagger-ui/**
   • /webjars/swagger-ui/**
   • /v3/api-docs/**

   例如Spring Security配置示例：

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

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