Spring Boot集成Swagger 2时swagger-ui页面404错误排查求助

问题描述 #

尝试为Spring Boot 3.0.4项目集成Swagger UI，访问http://localhost:8080/swagger-ui/index.html和http://localhost:8080/swagger-ui.html均返回404错误。项目使用Oracle OpenJDK 19，相关配置如下：

Maven依赖配置 #

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>
    <groupId>ru.racoonsoft</groupId>
    <artifactId>mm-gate</artifactId>
    <name>MMGate</name>
    <version>1.0</version>

    <properties>
        <java.version>19</java.version>
    </properties>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.0.4</version>
    </parent>

    <repositories>
        <repository>
            <id>racoonsoft-repository</id>
            <url>http://racoonsoft.ru:8081/artifactory/racoonsoft/</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

        <!-- Starter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>

        <!-- 其他依赖省略 -->
    </dependencies>

    <build>
        <finalName>spring-boot-crud</finalName>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>false</filtering>
            </resource>
        </resources>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <classifier>exec</classifier>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-assembly-plugin</artifactId>
                <version>3.3.0</version>
                <configuration>
                    <descriptorRefs>
                        <descriptorRef>jar-with-dependencies</descriptorRef>
                    </descriptorRefs>
                </configuration>
                <executions>
                    <execution>
                        <id>make-assembly</id>
                        <phase>package</phase>
                        <goals>
                            <goal>single</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Swagger配置类 #

@Configuration
public class SwaggerSettings {

    @Bean
    public Docket configApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

Web配置类 #

@Configuration
public class WebConfiguration extends WebMvcConfigurationSupport {

    @Autowired
    protected AuthService authService;
    @Autowired
    protected AdminInterceptor adminInterceptor;

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/assets");
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new GateAuthInterceptor(authService)).addPathPatterns("/gate/**");
        registry.addInterceptor(adminInterceptor).addPathPatterns("/admin/**");
    }
}

原因分析 #

1. Springfox与Spring Boot 3不兼容：Springfox 3.0.0基于Java EE开发，而Spring Boot 3.x采用Jakarta EE规范，两者API包路径不同（javax.* vs jakarta.*），导致核心依赖冲突，无法正常加载Swagger相关组件。
2. 静态资源映射覆盖：WebConfiguration中配置了/**的资源映射指向classpath:/assets，这会覆盖Spring Boot默认的静态资源处理逻辑，包括Swagger UI的静态文件（位于classpath:/META-INF/resources/webjars/下），导致无法访问Swagger页面。

解决方案 #

1. 替换为SpringDoc OpenAPI（推荐） #

Springfox已停止维护，Spring Boot 3官方推荐使用SpringDoc OpenAPI作为API文档工具：

• 移除所有Springfox依赖，添加SpringDoc依赖：

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

• 删除自定义的SwaggerSettings配置类，SpringDoc会自动扫描API接口并生成文档。

2. 修复静态资源映射 #

修改WebConfiguration的addResourceHandlers方法，避免覆盖全局静态资源路径，同时添加Swagger UI的资源映射：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    // 仅映射自定义assets路径，不要用/**
    registry.addResourceHandler("/assets/**")
            .addResourceLocations("classpath:/assets/");
    
    // 添加SpringDoc Swagger UI的资源映射
    registry.addResourceHandler("/swagger-ui/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/");
}

3. 访问Swagger UI #

启动项目后，访问http://localhost:8080/swagger-ui/index.html或简化路径http://localhost:8080/swagger-ui/即可查看API文档。

备选方案（不推荐） #

如果坚持使用Springfox，需要将Spring Boot版本降级到2.x（如2.7.x），同时调整Java版本到17及以下，适配Springfox的Java EE依赖。

内容的提问来源于stack exchange，提问作者user2160696