无法访问Swagger-UI页面问题排查求助

AI 小北

2026-7-13

问题排查与解决方案

依赖不完整
springdoc-openapi-starter-webmvc-api仅负责生成OpenAPI的JSON文档（即/api-docs路径），Swagger UI的界面展示需要额外引入springdoc-openapi-starter-webmvc-ui依赖。检查你的pom.xml（Maven）或build.gradle（Gradle），确认是否添加了该依赖：
Maven示例：
```
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>你的版本号</version>
</dependency>
```
Gradle示例：
```
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:你的版本号'
```
注意保持api和ui依赖的版本一致，避免版本不兼容。
Swagger UI访问路径错误
部分springdoc版本中，Swagger UI的默认访问路径已调整为/swagger-ui/（末尾带斜杠），而非/swagger-ui.html。尝试访问http://localhost:8080/swagger-ui/看是否能正常加载界面。
静态资源被拦截
即使Security放行了相关路径，若项目中自定义了Spring MVC的静态资源配置（比如实现了WebMvcConfigurer并重写addResourceHandlers方法），可能未将Swagger UI的静态资源路径纳入允许范围。需确保配置中包含：
```
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/swagger-ui/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/");
}
```
配置禁用了Swagger UI
检查application.properties或application.yml中是否存在禁用Swagger UI的配置：
```
# 若存在以下配置，将其删除或设为true
springdoc.swagger-ui.enabled=false
```
版本兼容性问题
确认springdoc依赖版本与你的Spring Boot版本匹配。例如springdoc v2.x系列要求Spring Boot 3.x，若你使用Spring Boot 2.x，需使用springdoc v1.x系列的依赖（如springdoc-openapi-ui而非starter版本）。