Spring Cloud Gateway中OpenAPI Swagger调用微服务API时Authorization Header缺失问题

核心问题分析 #

网关聚合Swagger UI后，授权输入的JWT令牌未被自动携带到转发至微服务的请求中，通常由以下原因导致：

• 网关同时混用springdoc-openapi和springfox两种Swagger实现，引发兼容性冲突
• 网关Swagger配置未全局添加安全认证要求，导致UI授权的令牌无法绑定到请求
• 网关路由/过滤器配置无意中移除了Authorization请求头
• 微服务API文档的安全配置未被网关正确聚合

分步解决方案 #

1. 统一Swagger依赖（移除冲突）

网关中同时引入springdoc-openapi-ui和springfox-boot-starter会导致底层逻辑冲突，必须二选一。推荐使用维护活跃的springdoc-openapi：

<!-- 移除springfox-boot-starter依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.15</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-gateway</artifactId>
    <version>1.6.15</version>
</dependency>

2. 修正网关Swagger配置类

确保配置类全局添加安全认证规则，并正确聚合微服务API文档：

import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import org.springdoc.core.GroupedOpenApi;
import org.springdoc.core.SwaggerUiConfigParameters;
import org.springframework.cloud.gateway.route.RouteDefinitionLocator;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@SecurityScheme(
    name = "BearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT"
)
public class GatewaySwaggerConfig {

    private final RouteDefinitionLocator routeDefinitionLocator;

    public GatewaySwaggerConfig(RouteDefinitionLocator routeDefinitionLocator) {
        this.routeDefinitionLocator = routeDefinitionLocator;
    }

    @Bean
    public GroupedOpenApi apis(SwaggerUiConfigParameters swaggerUiConfigParameters) {
        // 自动识别网关路由，聚合所有微服务API
        routeDefinitionLocator.getRouteDefinitions().subscribe(routeDefinition -> {
            swaggerUiConfigParameters.addGroup(routeDefinition.getId());
        });
        return GroupedOpenApi.builder()
                .group("all-services")
                .pathsToMatch("/**")
                .build();
    }

    @Bean
    public OpenAPI customOpenAPI() {
        // 全局添加JWT认证要求，确保令牌被携带
        return new OpenAPI()
                .addSecurityItem(new SecurityRequirement().addList("BearerAuth"));
    }
}

3. 配置网关路由与跨域规则

• 确保网关路由正确代理微服务的API文档路径：

spring:
  cloud:
    gateway:
      routes:
        # 微服务业务路由
        - id: service-a
          uri: lb://service-a
          predicates:
            - Path=/service-a/**
          filters:
            - RewritePath=/service-a/(?<path>.*), /$\{path}
        # 微服务API文档路由（供网关聚合）
        - id: service-a-api-docs
          uri: lb://service-a
          predicates:
            - Path=/v3/api-docs/service-a
          filters:
            - RewritePath=/v3/api-docs/service-a, /v3/api-docs
        # 同理配置其他微服务的路由和API文档路由

• 若存在跨域配置，需明确允许Authorization头：

spring:
  cloud:
    gateway:
      globalcors:
        cors-configurations:
          '[/**]':
            allowed-origins: "*"
            allowed-methods: "*"
            allowed-headers: "Authorization, Content-Type"
            allow-credentials: true

4. 确认微服务端配置正确性

微服务需确保API文档的安全配置可被网关访问：

# 微服务application.yml
springdoc:
  api-docs:
    path: /v3/api-docs
    enabled: true
  swagger-ui:
    enabled: true

验证步骤 #

1. 启动网关和所有微服务
2. 访问网关Swagger UI（默认路径/swagger-ui.html）
3. 点击"Authorize"按钮输入JWT令牌
4. 调用任意微服务API，查看请求Curl是否包含Authorization: Bearer <token>头

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