Spring Boot项目打开Swagger出现Whitelabel Error Page问题求助

问题现象 #

打开Swagger页面时出现白标错误，错误信息如下：

Whitelabel Error Page
This application has no explicit mapping for /error, so you are seeing this as a fallback.

尝试访问的所有Swagger相关URL都返回该错误：

• http://localhost:8080/swagger-ui.html
• http://localhost:8080/swagger-ui/
• http://localhost:8080/swagger-ui/index.html
• http://localhost:8080/swagger-ui
• http://localhost:8080/v2/api-docs

项目配置信息 #

POM文件 #

<?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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.1.3</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>br.com.boucher</groupId>
    <artifactId>boucher-core</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <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>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <version>8.1.0</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</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.11.0</version>
                <configuration>
                    <source>11</source>
                    <target>11</target>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>1.18.30</version>
                        </path>
                        <path>
                            <groupId>org.mapstruct</groupId>
                            <artifactId>mapstruct-processor</artifactId>
                            <version>1.5.5.Final</version>
                        </path>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok-mapstruct-binding</artifactId>
                            <version>0.2.0</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

Swagger配置类 #

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

Spring启动类 #

@SpringBootApplication
public class BoucherCoreApplication {

    public static void main(String[] args) {

        SpringApplication.run(BoucherCoreApplication.class, args);
    }

}

控制器示例 #

@RestController
@RequestMapping("boucher/v1/estabelecimento")
@RequiredArgsConstructor
public class EstabelecimentoController {

    private final EstabelecimentoServicePort estabelecimentoServicePort;

    @PostMapping
    public ResponseEntity<?> save(@RequestBody @Valid EstabelecimentoSaveRequest request){

        Estabelecimento estabelecimento = estabelecimentoServicePort.save(EstabelecimentoMapper.INSTANCE.mapFrom(request));
        return new ResponseEntity<>(estabelecimento,HttpStatus.CREATED);
    }

    @GetMapping
    public ResponseEntity<?> getAll(@RequestParam("latitude") Double latitude,
                                    @RequestParam("longitude") Double longitude,
                                    @RequestParam("raio") Double raio,
                                    @RequestParam(name = "page", required = false, defaultValue = "0") int page,
                                    @RequestParam(name = "size", required = false, defaultValue = "10") int size){

        Paginacao paginacao = new Paginacao(page,size);
        var estabelecimentos = estabelecimentoServicePort.getAllByRadius(latitude,longitude,raio,paginacao);
        return new ResponseEntity<>(estabelecimentos,HttpStatus.OK);
    }
    @GetMapping("/{id}")
    public ResponseEntity<?> get(@PathVariable Long id){
        return new ResponseEntity<>(estabelecimentoServicePort.getById(id),HttpStatus.OK);
    }
}

已尝试的操作 #

• 将Swagger版本改为2.9.x；
• 在SwaggerConfig和启动类添加@EnableSwagger2注解；
• 调整POM依赖。

问题根源及解决方案 #

根源 #

你使用的Spring Boot版本是3.1.3，而Springfox 3.0.0（包括2.x版本）不支持Spring Boot 3.x。Spring Boot 3基于Spring 6，而Springfox的最后一个稳定版本只兼容到Spring Boot 2.6.x，后续停止维护了，所以无论怎么调整配置都无法正常加载Swagger。

解决方案 #

改用SpringDoc OpenAPI，这是Spring官方推荐的、兼容Spring Boot 3的API文档工具，步骤如下：

1. 替换依赖：移除POM中的Springfox依赖，添加SpringDoc依赖：

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

2. 调整配置类：删除原有的SwaggerConfig类（SpringDoc默认自动配置），如果需要自定义API文档信息，可以创建如下配置类：

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Boucher Core API")
                        .version("1.0")
                        .description("Boucher Core项目的API文档"));
    }
}

3. 访问正确的URL：
   • Swagger UI页面：http://localhost:8080/swagger-ui/index.html
   • OpenAPI接口文档：http://localhost:8080/v3/api-docs

完成以上步骤后，重启项目即可正常访问Swagger页面。

内容的提问来源于stack exchange，提问作者Gabriel Reis Ritter