Spring Cloud Gateway集成Swagger出现白标错误页问题求助

问题场景 #

在基于spring-cloud-starter-gateway的Spring Boot应用中集成Swagger API文档时遇到白标错误页：移除Gateway依赖后，访问Swagger UI正常；添加Gateway依赖后，访问Swagger UI出现白标错误。相关配置如下：

初始配置类 #

@OpenAPIDefinition
@Configuration
public class SwaggerConfiguration {
    @Bean
    public OpenAPI baseOpenAPI(){
        return new OpenAPI().info(
                new Info()
                        .title("This is a test")
                        .version("0.1")
        );
    }
}

控制器代码 #

@RestController
public class HelloWorldController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

初始build.gradle配置 #

plugins {
    id 'java'
    id 'org.springframework.boot' version '2.7.11'
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
}

group = 'com.noob234'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}
	ext {
    set('springCloudVersion', "2021.0.7")
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-webflux'
    implementation 'org.springframework.cloud:spring-cloud-starter-gateway'
    implementation 'org.springdoc:springdoc-openapi-ui:1.6.15'
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'io.projectreactor:reactor-test'
}

dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
    }
}

tasks.named('test') {
    useJUnitPlatform()
}

补充尝试的配置 #

替换为WebFlux专用依赖，并添加路由配置到application.properties：

spring.application.name=gateway
server.port=8081
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.enabled=true
spring.cloud.gateway.routes[0].id=swagger-ui
spring.cloud.gateway.routes[0].uri=http://localhost:8081
spring.cloud.gateway.routes[0].predicates[0]=Path=/swagger-ui.html

spring.cloud.gateway.routes[1].id=api-docs
spring.cloud.gateway.routes[1].uri=http://localhost:8081
spring.cloud.gateway.routes[1].predicates[0]=Path=/v3/api-docs

能否复现问题 #

可以复现，问题根源有两点：

1. 初始配置使用了适配Servlet环境的springdoc-openapi-ui，但Spring Cloud Gateway基于WebFlux（Reactive环境），依赖环境不兼容，导致Swagger静态资源无法正确加载。
2. 补充尝试中的路由配置存在错误：将请求路由到自身会引发循环调用，且未覆盖Swagger UI所需的全部静态资源路径（如/swagger-ui/**下的JS、CSS文件），依然会导致白标错误。

解决步骤 #

1. 修正依赖配置 #

移除springdoc-openapi-ui，替换为WebFlux专用的依赖：

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-webflux'
    implementation 'org.springframework.cloud:spring-cloud-starter-gateway'
    // 使用WebFlux适配的SpringDoc依赖
    implementation 'org.springdoc:springdoc-openapi-webflux-ui:1.6.15'
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'io.projectreactor:reactor-test'
}

注：springdoc-openapi-webflux-core已被springdoc-openapi-webflux-ui间接引入，无需单独添加。

2. 清理无效路由配置 #

删除application.properties中指向自身的Swagger路由配置，保留基础配置即可：

spring.application.name=gateway
server.port=8081
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.enabled=true

SpringDoc会自动在WebFlux环境中注册Swagger相关端点，无需手动配置路由指向自身。

3. 排除Swagger路径的Gateway拦截 #

如果应用中有全局过滤器或自定义路由断言，需要确保排除以下Swagger相关路径，避免被Gateway拦截：

• /swagger-ui/**
• /v3/api-docs/**
• /swagger-resources/**

4. 验证结果 #

启动应用后，访问http://localhost:8081/swagger-ui.html即可正常查看Swagger文档，/hello接口会被自动扫描并展示。

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