<think>
根据描述，`/v
2/
api-docs`可以
访问（说明
Swagger的
API文档
JSON已经生成），但是
访问`/
swagger-ui
.html`出现404。这种情况通常发生在
使用Springfox
Swagger时，并且可能是由于以下原因之一：
1
. **依赖问题**：缺少
Swagger UI的依赖或者版本不兼容。
2. **路径错误**：新版本的Springfox
Swagger可能更改了默认的
Swagger UI路径。
3
. **静态资源问题**：Spring Boot没有正确映射
Swagger UI的静态资源。
### 解决方案
#### 1
. 确认依赖
确保在`pom
.xml`中包含了正确的Springfox
Swagger UI依赖。例如：
```xml
<dependency>
<groupId>io
.springfox</groupId>
<artifactId>springfox
-swagger2</artifactId>
<version>
2.9
.2</version>
</dependency>
<dependency>
<groupId>io
.springfox</groupId>
<artifactId>springfox
-swagger-ui</artifactId>
<version>
2.9
.2</version>
</dependency>
```
####
2. 检查默认
访问路径
在Springfox
Swagger中，
Swagger UI的默认
访问路径是`/
swagger-ui
.html`。但是，有时候由于上下文路径（server
.servlet
.context
-path）的配置，实际路径可能是`/{context
-path}/
swagger-ui
.html`。例如，如果设置了`server
.servlet
.context
-path=/
api`，那么
访问路径应为`
http://localhost:8080/
api/
swagger-ui
.html`。
#### 3
. 添加
Swagger配置类
确保有一个配置类启用
Swagger。例如：
```java
@Configuration
@Enable
Swagger2
public class
SwaggerConfig {
@Bean
public Docket
api() {
return new Docket(DocumentationType
.SWAGGER_
2)
.select()
.apis(RequestHandlerSelectors
.any())
.paths(PathSelectors
.any())
.build();
}
}
```
#### 4
. 处理静态资源映射
如果以上步骤都正确，但问题仍然存在，可能是静态资源映射的问题。可以尝试添加一个Web配置类，显式映射
Swagger UI的静态资源。在Spring Boot
2中，可以这样做：
```java
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry
.addResourceHandler("
swagger-ui
.html")
.addResourceLocations("classpath
:/META
-INF/resources/");
registry
.addResourceHandler("/webjars/**")
.addResourceLocations("classpath
:/META
-INF/resources/webjars/");
}
}
```
#### 5
. 检查Spring Security拦截
如果项目
使用了Spring Security，需要确保放行
Swagger相关的资源。例如：
```java
@Override
public void configure(WebSecurity web) throws Exception {
web
.ignoring()
.antMatchers(
"/v
2/
api-docs",
"/
swagger-resources/**",
"/
swagger-ui
.html",
"/webjars/**"
);
}
```
### 完整示例代码
####
Swagger配置类
```java
@Configuration
@Enable
Swagger2
public class
SwaggerConfig {
@Bean
public Docket
api() {
return new Docket(DocumentationType
.SWAGGER_
2)
.select()
.apis(RequestHandlerSelectors
.basePackage("com
.example
.controller"))
.paths(PathSelectors
.any())
.build()
.apiInfo(
apiInfo());
}
private
ApiInfo
apiInfo() {
return new
ApiInfoBuilder()
.title("
API文档")
.description("更多请关注
...")
.version("1
.0")
.build();
}
}
```
#### 静态资源处理配置
```java
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry
.addResourceHandler("
swagger-ui
.html")
.addResourceLocations("classpath
:/META
-INF/resources/");
registry
.addResourceHandler("/webjars/**")
.addResourceLocations("classpath
:/META
-INF/resources/webjars/");
}
}
```
#### Spring Security配置（如果
使用）
```java
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
@Override
public void configure(WebSecurity web) throws Exception {
web
.ignoring()
.antMatchers(
"/v
2/
api-docs",
"/
swagger-resources/**",
"/
swagger-ui
.html",
"/webjars/**"
);
}
// 其他安全配置
...
}
```
### 验证
访问`
http://localhost:8080/
swagger-ui
.html`，应该能够看到
Swagger UI界面。
### 注意事项
- 如果
使用Spring Boot
2.6及以上版本，由于路径匹配策略的更改（从`AntPathMatcher`变为`PathPatternParser`），可能会导致
Swagger资源无法
访问。可以在`application
.properties`中设置：
```properties
spring
.mvc
.pathmatch
.matching
-strategy=ant_path_matcher
```
### 替代方案：迁移到SpringDoc
如果问题依旧无法解决，建议迁移到SpringDoc（支持Open
API 3）。迁移步骤：
1
. 移除Springfox依赖
2. 添加SpringDoc依赖：
```xml
<dependency>
<groupId>org
.springdoc</groupId>
<artifactId>springdoc
-open
api-ui</artifactId>
<version>1
.6
.14</version>
</dependency>
```
3
. 访问路径变为`
http://localhost:8080/
swagger-ui/index
.html`
§§相关问题§§
:
1
. 如何在
Swagger中配置OAuth
2认证？
2. Springfox
和SpringDoc的主要区别是什么？
3
. 如何自定义
Swagger UI的界面？
4
. 在
Swagger中如何隐藏某些接口？
</think>### 解决 `/v
2/
api-docs` 可
访问但 `/
swagger-ui
.html` 404 的问题
这个问题通常发生在
使用 **Springfox
Swagger** 的旧项目中，主要原因是：
1
. **路径错误**：新版本 Springfox 默认 UI 路径已改变
2. **静态资源未正确映射**：
Swagger UI 资源未被正确加载
3
. **版本兼容性问题**：依赖版本与 Spring Boot 不匹配
以下是完整解决方案：
---
### 1
. 验证依赖版本（关键步骤）
在 `pom
.xml` 中
使用推荐版本组合：
```xml
<!
-- Springfox
Swagger 2 -->
<dependency>
<groupId>io
.springfox</groupId>
<artifactId>springfox
-swagger2</artifactId>
<version>
2.10
.5</version> <!
-- 支持 Spring Boot
2.5 及以下
-->
</dependency>
<dependency>
<groupId>io
.springfox</groupId>
<artifactId>springfox
-swagger-ui</artifactId>
<version>
2.10
.5</version>
</dependency>
<!
-- 或者
使用 Springfox 3+
-->
<dependency>
<groupId>io
.springfox</groupId>
<artifactId>springfox
-boot
-starter</artifactId>
<version>3
.0
.0</version> <!
-- 支持 Spring Boot
2.6+
-->
</dependency>
```
> **版本选择规则**：
>
- Spring Boot <
2.6：用 Springfox
2.10
.5
>
- Spring Boot ≥
2.6：用 Springfox 3
.x
---
###
2. 修复资源映射配置
添加资源处理器配置类：
```java
@Configuration
public class
SwaggerWebConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// Springfox
2.x 资源路径
registry
.addResourceHandler("
swagger-ui
.html")
.addResourceLocations("classpath
:/META
-INF/resources/");
registry
.addResourceHandler("/webjars/**")
.addResourceLocations("classpath
:/META
-INF/resources/webjars/");
}
// 解决 Spring Boot
2.6+ 路径匹配问题
@Bean
public static BeanPostProcessor pathMatcherPostProcessor() {
return new BeanPostProcessor() {
@Override
public Object postProcessAfterInitialization(Object bean, String beanName) {
if (bean instanceof WebMvcProperties) {
((WebMvcProperties) bean)
.getPathmatch()
.setMatchingStrategy(
MatchingStrategy
.ANT_PATH_MATCHER
);
}
return bean;
}
};
}
}
```
---
### 3
. 检查
Swagger 配置类
确保配置类包含正确的路径设置：
```java
@Configuration
@Enable
Swagger2
public class
SwaggerConfig {
@Bean
public Docket
api() {
return new Docket(DocumentationType
.SWAGGER_
2)
.select()
.apis(RequestHandlerSelectors
.basePackage("com
.yourpackage
.controller"))
.paths(PathSelectors
.any())
.build()
.apiInfo(
apiInfo());
}
private
ApiInfo
apiInfo() {
return new
ApiInfoBuilder()
.title("
API Documentation")
.description("接口文档")
.version("1
.0")
.build();
}
}
```
---
### 4
. 尝试备用
访问路径
Springfox 3
.x 默认路径已变更：
```
# Springfox
2.x
http://localhost:8080/
swagger-ui
.html
# Springfox 3
.x
http://localhost:8080/
swagger-ui/index
.html?configUrl=/v3/
api-docs/
swagger-config
```
---
### 5
. 迁移到 SpringDoc（推荐长期方案）
如问题持续存在，建议迁移到更现代的 SpringDoc：
```xml
<!
-- 替换 Springfox 依赖
-->
<dependency>
<groupId>org
.springdoc</groupId>
<artifactId>springdoc
-open
api-ui</artifactId>
<version>1
.6
.14</version>
</dependency>
```
访问路径变为：`
http://localhost:8080/
swagger-ui/index
.html`
---
### 验证步骤
1
. 访问 `/
swagger-resources` 检查端点：
```
http://localhost:8080/
swagger-resources
```
应返回
JSON 配置列表
2. 检查控制台日志：
```
Mapped URL path [/v
2/
api-docs] onto method [springfox
.documentation
.swagger2.web
.Swagger2Controller#getDocumentation()]
```
3
. 直接
访问 UI 资源：
```
http://localhost:8080/webjars/springfox
-swagger-ui/springfox
.js
```
---
### 常见问题排查表
| 现象 | 解决方案 |
|
------|
----------|
| Whitelabel Error Page | 检查 `WebMvcConfigurer` 资源映射 |
| 控制台
报 `No mapping for GET` | 添加 `spring
.mvc
.pathmatch
.matching
-strategy=ant_path_matcher` 到 `application
.properties` |
| 能
访问 `/v
2/
api-docs` 但 UI 空白 | 清除浏览器缓存，检查控制台 JS 错误 |
| Spring Boot
2.6+
报错 | 降级到 Spring Boot
2.5
.x 或
使用 SpringDoc |
这是因为spring-mvc.xml一个配置文件没有使用所导致的。
最低0.47元/天 解锁文章
扫一扫
7257
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
