Spring Boot 中访问 Swagger UI 报 404 not found 错误

前言

阅读本文前请先确定访问 swagger-ui 的路径是否正确,本文描述的 404 错误与访问路径无关。

问题描述

我在 Spring Boot 中使用 Springdoc 整合 OpenAPI 3.0 生成 API 文档时,访问 Swagger UI 报 404,而其他的配置均正确,访问地址为 http://localhost:8085/swagger-ui.html

但是在请求 http://localhost:8085/v3/api-docs/swagger-confighttp://localhost:8085/v3/api-docs 却是成功返回数据的。

访问swagger-ui.html报404

(提示:访问 /swagger-ui.html 会跳转 /swagger-ui/index.html,这是 Springdoc 做的内部重定向,这没问题。)

后来在 Github 上找到和我一模一样的问题:404 not found on swagger UI

有人说 IDEA 没有加载 webjars-locator-core 依赖,但是我在 IDEA 中能看到 webjars-locator-core 依赖。

看到有人提示覆盖 WebMvcConfigurationSupport 中的 Swagger UI 配置:

1
2
3
4
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/swagger-ui/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/3.45.0/");
}

我试了试,居然能成功访问到 Swagger UI。

错误分析

通过查看在 404 not found on swagger UI 的讨论,我开始找错误原因, issues 中有提到 WebMvcConfigurationSupport ,于是我开始找项目中是不是用到 WebMvcConfigurationSupport ,发现我在处理跨域时新增了一个配置,配置类继承了 WebMvcConfigurationSupport

1
2
3
4
5
6
7
8
9
10
11
12
13
@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {

@Override
protected void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/**")
.allowedOrigins("*")
.allowCredentials(true)
.allowedHeaders("GET", "POST", "PUT", "DELETE", "OPTIONS")
.allowedHeaders("Authorization", "Cache-Control", "Content-Type")
.maxAge(3600);
}
}

看到这里大概明白问题所在了,尝试把这个配置删掉,重新启动项目,访问 Swaggger UI,成功访问。

这个配置应该是导致没有加载 swagger-ui 资源的问题所在,所以报 404。

通过查看 springdoc-openapi-ui- {version} .jar 代码发现,springdoc-openapi-ui 提供了 org.springdoc.webmvc.ui.SwaggerWebMvcConfigureraddResourceHandlers 方法来添加 swagger-ui 的资源,但是 SwaggerWebMvcConfigurer.addResourceHandlers 方法并没有被调用,也就没有加载 swagger-ui 映射。

swagger-ui资源加载代码

但是 springdoc-openapi-ui 是自动配置 swagger-ui 的,到这里怎么会失效了呢? 原来,在我的配置类 WebMvcConfig 中继承了 WebMvcConfigurationSupport,而继承 WebMvcConfigurationSupport 后,Spring Boot 的自动配置就会失效,需要你自己去配置。因此 SwaggerWebMvcConfigurer.addResourceHandlers 方法没有被执行。

因此,加上以下这段代码后能访问到 Swagger UI 就不难理解了。

1
2
3
4
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/swagger-ui/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/3.45.0/");
}

但是,这样使用之后,如果项目中还有其他的配置都需要我们手动配置,这很麻烦,也不推荐。推荐实现 WebMvcConfigurer 接口来添加配置,看以下的方法一。

解决方案

方法一:实现 WebMvcConfigurer 接口来替代 WebMvcConfigurationSupport(推荐)

使用实现 WebMvcConfigurer 接口来替代 WebMvcConfigurationSupport,不用再添加其他配置,springdoc-openapi-ui 会自动装配 swagger-ui 的配置。

1
2
3
4
5
6
7
8
9
10
11
12
13
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/**")
.allowedOrigins("*")
.allowCredentials(true)
.allowedHeaders("GET", "POST", "PUT", "DELETE", "OPTIONS")
.allowedHeaders("Authorization", "Cache-Control", "Content-Type")
.maxAge(3600);
}
}

推荐使用这种方式。

方法二:手动添加 swagger-ui 的资源映射配置

继续使用继承 WebMvcConfigurationSupport 接口的配置,手动添加 swagger-ui 的资源映射配置:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {

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

@Override
protected void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/**")
.allowedOrigins("*")
.allowCredentials(true)
.allowedHeaders("GET", "POST", "PUT", "DELETE", "OPTIONS")
.allowedHeaders("Authorization", "Cache-Control", "Content-Type")
.maxAge(3600);
}
}

其中的 swagger-ui 映射路径中 classpath:/META-INF/resources/webjars/swagger-ui/3.49.0/ 的 swagger-ui 版本号可在 IDEA 的 Maven 面板中查看 springdoc-openapi-ui 的依赖:

swagger-ui版本

参考文档

  1. 404 not found on swagger UI