如何通过声明式方式启用Swagger UI中的Authorize按钮？

针对网关中 Swagger UI 无法正常加载 JWT 认证输入框的问题，核心是要确保全局注册 JWT 认证方案并关联到所有聚合接口，以下是具体的声明式配置步骤：

1. 核心配置思路 #

网关的 Swagger UI 是聚合多个下游服务的接口文档，因此需要在网关的 OpenAPI 全局配置中定义认证方案，并强制所有接口关联该方案，而不是将注解随意放在主类或普通控制器中。

2. 具体代码实现（基于 SpringDoc OpenAPI，当前主流方案） #

步骤1：定义 JWT 认证方案配置类 #

创建专门的配置类，通过注解声明 JWT 认证的规则：

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import org.springframework.context.annotation.Configuration;

@Configuration
@OpenAPIDefinition
@SecurityScheme(
    name = "BearerAuth", // 认证方案名称，后续要引用
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT", // 指定为JWT格式
    in = io.swagger.v3.oas.annotations.enums.ParameterIn.HEADER
)
public class GatewayOpenApiSecurityConfig {
}

步骤2：全局关联认证方案 #

配置 OpenAPI Bean，将上述定义的认证方案全局绑定到所有接口：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiGlobalConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                // 关联之前定义的认证方案名称
                .addSecurityItem(new SecurityRequirement().addList("BearerAuth"));
    }
}

步骤3：网关 Swagger 聚合配置 #

确保网关正确聚合下游服务的接口文档：

import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class GatewaySwaggerAggregateConfig {

    @Bean
    public GroupedOpenApi gatewayAggregateApi() {
        return GroupedOpenApi.builder()
                .group("gateway-all-services")
                .pathsToMatch("/**") // 匹配所有路由路径
                .build();
    }
}

步骤4：配置文件补充（application.yml） #

开启 SpringDoc 网关支持：

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
  gateway:
    enabled: true # 关键：开启网关的Swagger聚合支持

3. 验证配置正确性 #

访问网关的 OpenAPI JSON 地址（默认 /v3/api-docs），检查是否包含以下内容：

{
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ]
}

如果上述字段存在，说明配置生效，此时 Swagger UI 的 Authorize 按钮点击后会正常显示 JWT 输入框。

4. 问题根源说明 #

之前的配置失效是因为：

• 网关的 Swagger 聚合逻辑不会自动识别主类/普通控制器上的 @SecurityScheme 注解
• 未全局添加 SecurityRequirement，导致 Swagger UI 无法感知需要加载认证输入框

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