springboot2.6.13集成springdoc-openapi-ui 1.6.14和springdoc-openapi-webflux-ui 1.6.14 访问http://localhost:8080/swagger-ui/index.html找不到页面

### 已知问题分析 当在 Spring Boot 2.6.13 中集成 `springdoc-openapi-ui` 和 `springdoc-openapi-webflux-ui` 并访问 Swagger 页面时，如果返回 404 错误，则可能是由于以下原因引起的： 1. **依赖版本不一致**：尽管指定了 `springdoc-openapi-ui` 和 `springdoc-openapi-webflux-ui` 的版本为 1.6.14，但如果这些版本与 Spring Boot 2.6.13 不完全兼容，可能会导致功能异常[^1]。 2. **静态资源映射问题**：Swagger UI 是通过静态资源加载的，如果项目中未正确配置静态资源路径或被其他拦截器覆盖，则可能导致页面无法正常渲染。 3. **WebFlux 或 WebMVC 模式混淆**：Spring Boot 支持两种不同的编程模型（同步和异步），而 `springdoc-openapi-*` 对这两种模式有不同的适配方式。如果项目中混合使用了两者，可能会引发冲突。 --- ### 解决方案 #### 方法一：确认并调整依赖版本 确保所使用的 `springdoc-openapi-ui` 和 `springdoc-openapi-webflux-ui` 版本与当前 Spring Boot 版本兼容。虽然您已指定版本号为 1.6.14，但仍需验证其稳定性。推荐升级至更高版本（如 1.7.x 系列）以获得更好的支持。 ```xml <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.7.0</version> </dependency> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-webflux-ui</artifactId> <version>1.7.0</version> </dependency> ``` 注意：始终查阅官方文档或 Maven Central Repository 获取最新稳定版[^1]。 --- #### 方法二：检查静态资源配置 默认情况下，`springdoc-openapi-ui` 将 Swagger UI 部署到 `/v3/api-docs` 和 `/swagger-ui.html` 路径下。如果您修改过 Spring Boot 的静态资源目录或者启用了额外的安全框架（如 Spring Security），则需要手动声明允许访问这些路径。 ##### 示例代码：放行特定 URL 对于基于 WebFlux 的项目，可通过如下方式配置权限豁免列表： ```java import org.springframework.context.annotation.Bean; import org.springframework.security.config.web.server.ServerHttpSecurity; import org.springframework.security.web.server.SecurityWebFilterChain; @Bean public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) { return http.authorizeExchange() .pathMatchers("/v3/api-docs/**", "/swagger-ui.html", "/webjars/**").permitAll() .anyExchange().authenticated() .and() .csrf().disable() .build(); } ``` 上述代码确保 API 文档及相关前端资源能够绕过身份认证直接展示给用户[^2]。 --- #### 方法三：排查上下文根路径影响 有时部署环境中设置了自定义的应用程序上下文路径（context-path）。这种设定会改变实际对外暴露的服务地址形式。例如原本期望打开的是 `http://localhost:8080/swagger-ui.html` ，但实际上应该尝试拼接完整前缀后的链接形似于 `http://localhost:8080/your-context-root/swagger-ui.html`. 可以在 `application.properties` 文件里查找是否存在类似这样的条目: ```properties server.servlet.context-path=/myapp ``` 如果有，请记得将其纳入最终测试网址构成之中[^3]. --- #### 方法四：启用调试日志辅助诊断 开启更详尽的日志记录可以帮助快速定位根本原因所在位置。编辑 `logback-spring.xml` 添加以下内容或将对应级别设成 TRACE : ```xml <logger name="org.springdoc" level="DEBUG"/> <root level="INFO"> <appender-ref ref="CONSOLE"/> </root> ``` 观察控制台输出寻找有关 swagger ui 加载过程中的蛛丝马迹提示信息。 --- ### 示例代码片段 这里给出一个典型的 POM 定义以及简单的 REST 控制器例子供参考对比： ```xml <!-- pom.xml --> <dependencies> <!-- SpringDoc OpenAPI UI for MVC and WebFlux --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.7.0</version> </dependency> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-webflux-ui</artifactId> <version>1.7.0</version> </dependency> </dependencies> ``` ```java // Controller Example @RestController @RequestMapping("/example") public class ExampleController { @GetMapping("/hello") public Mono<String> helloWorld() { return Mono.just("Hello from Reactive Spring!"); } } ``` --- ### 总结 综上所述，解决 Spring Boot 2.6.13 集成 `springdoc-openapi-ui` 及 `springdoc-openapi-webflux-ui` 访问 Swagger 页面报 404 的问题可以从多个角度入手，包括但不限于更新依赖、审查安全策略、核验上下文路径设置以及利用增强型日志工具协助追踪线索等手段逐一排除障碍直至恢复正常运作状态为止。 ---