项目集成Swagger遇白标错误页面问题求助

核心问题排查 #

1. 依赖冗余冲突：springfox-boot-starter已包含springfox-swagger2和springfox-swagger-ui的核心功能，重复引入这两个独立依赖会导致组件冲突
2. Java版本不匹配：项目指定Java 17，但maven-compiler-plugin的source/target配置为1.8，编译环境与运行环境版本不一致
3. 访问路径错误：配置了上下文路径/swagger-u，但访问时未添加该前缀；同时Springfox 3.x的Swagger UI默认路径是/swagger-ui/（无.html后缀）
4. API扫描范围过窄：PathSelectors.ant("/*")仅能匹配一级路径，无法覆盖项目中所有层级的API接口
5. 注解冗余：Springfox 3.x版本无需@EnableSwagger2注解，starter会自动完成配置

修复方案 #

1. 清理pom.xml冗余依赖并修正Java版本配置 #

<properties>
    <java.version>17</java.version>
    <org.mapstruct.version>1.5.5.Final</org.mapstruct.version>
</properties>
<dependencies>
    <!-- 仅保留Springfox Starter，已集成swagger2和swagger-ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.16.12</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>1.5.5.Final</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <!-- 与项目Java版本保持一致 -->
                <source>17</source>
                <target>17</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${org.mapstruct.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

2. 更新Swagger配置类 #

移除冗余注解，扩大API路径扫描范围：

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ecommerce.app"))
                // 匹配所有层级的API路径
                .paths(PathSelectors.ant("/**"))
                .build();
    }
}

3. 使用正确的访问地址 #

结合配置的上下文路径，正确的Swagger UI访问地址为：

http://localhost:8080/swagger-u/swagger-ui/

可选优化 #

如果不需要自定义API分组、参数规则等，可以直接删除SwaggerConfig类，springfox-boot-starter会自动启用Swagger并扫描所有Controller。

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