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

前言

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

Swagger 2：http://localhost:8080/swagger-ui.html
Swagger 3（OpenAPI 3.0）：http://localhost:8080/swagger-ui/index.html

问题描述

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

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

（提示：访问 /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 配置：

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：

@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.SwaggerWebMvcConfigurer 的 addResourceHandlers 方法来添加 swagger-ui 的资源，但是 SwaggerWebMvcConfigurer.addResourceHandlers 方法并没有被调用，也就没有加载 swagger-ui 映射。

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

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

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 的配置。

@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 的资源映射配置：

@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 的依赖：

参考文档

404 not found on swagger UI