Spring Boot项目集成Swagger UI遭遇404错误求助

问题场景 #

开发Spring Boot项目时，集成Swagger UI用于API文档管理，但访问Swagger UI页面时出现404错误。

环境配置 #

• Spring Boot版本：2.6.3
• Java版本：11
• 构建工具：Maven

pom.xml依赖 #

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.24</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>com.github.vladimir-bukhtoyarov</groupId>
    <artifactId>bucket4j-core</artifactId>
    <version>7.3.0</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
    <version>2.14.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.3</version>
</dependency>

Swagger配置类 #

package com.tenpo.pruebatenpo.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API de Transacciones")
                        .version("1.0")
                        .description("Documentación de la API de Transacciones"));
    }
}

错误表现 #

访问地址 http://localhost:8080/swagger-ui/index.html 时返回404，日志输出如下警告：

2025-01-15T18:04:11.783-03:00  WARN 24704 --- [pruebatenpo] [nio-8080-exec-8] o.s.web.servlet.PageNotFound             : No mapping for GET /swagger-ui/index.html

2025-01-15T18:04:11.785-03:00  WARN 24704 --- [pruebatenpo] [nio-8080-exec-8] .m.m.a.ExceptionHandlerExceptionResolver : Resolved [org.springframework.web.servlet.NoHandlerFoundException: No endpoint GET /swagger-ui/index.html.]

解决方案 #

1. 修复版本兼容性 #

Spring Boot 2.6.x与springdoc-openapi-starter-webmvc-ui 2.8.x存在版本冲突，将springdoc依赖版本调整为适配2.6.x的稳定版：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>1.6.14</version>
</dependency>

2. 放行Swagger静态资源 #

若项目自定义了WebMvcConfigurer，需添加Swagger相关资源的映射规则，避免静态资源被拦截：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/");
        registry.addResourceHandler("/v3/api-docs/**")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
}

3. 调整访问路径 #

springdoc 1.x版本的Swagger UI默认访问路径为 http://localhost:8080/swagger-ui.html，而非/swagger-ui/index.html，更换路径后重试。

4. 修改MVC路径匹配策略 #

Spring Boot 2.6.x默认启用PATH_PATTERN_PARSER，可能导致路径匹配异常，在application.properties中修改为旧策略：

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

验证步骤 #

1. 执行mvn clean install更新依赖
2. 重启Spring Boot应用
3. 访问对应路径确认Swagger UI正常加载

内容的提问来源于stack exchange，提问作者Roberto Caamaño Riquelme