Spring Boot 3集成OpenAPI时Authorization请求头无法传递求助

环境信息 #

• Java 17
• 服务基于Spring Boot 3
• OpenAPI依赖：org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0、org.springdoc:springdoc-openapi-starter-common:2.1.0、org.springdoc:springdoc-openapi-ui:1.7.0

问题描述 #

升级到OpenAPI后，尝试通过请求头传递authorization值时，Chrome开发者控制台里看不到这个请求头。之前用SpringFox时该功能正常，换成其他名称的请求头（比如authorization1）则能正常显示并传递。

正常场景：使用非authorization名称的请求头 #

API定义代码：

@GetMapping(value = "somevalue")
@Operation(summary = "Get something")
@Parameters({
    @Parameter(
        name = "authorization1",
        description = "Access Token",
        required = true,
        in = ParameterIn.HEADER,
        schema = @Schema(implementation = String.class),
        example = "12345"),
    @Parameter(
        name = "code",
        description = "Code",
        required = true,
        in = ParameterIn.HEADER,
        schema = @Schema(allowableValues = {"A", "B", "C", "D"})
    )
})
public List<IIRDto> getII(
    @Parameter(required = true) @NotNull @RequestParam List<Long> idsOfSomething
) {
    // 业务代码
}

异常场景：使用authorization名称的请求头 #

API定义代码：

@GetMapping(value = "somevalue")
@Operation(summary = "Get something")
@Parameters({
    @Parameter(
        name = "authorization",
        description = "Access Token",
        required = true,
        in = ParameterIn.HEADER,
        schema = @Schema(implementation = String.class),
        example = "12345"),
    @Parameter(
        name = "code",
        description = "Code",
        required = true,
        in = ParameterIn.HEADER,
        schema = @Schema(allowableValues = {"A", "B", "C", "D"})
    )
})
public List<IIRDto> getII(
    @Parameter(required = true) @NotNull @RequestParam List<Long> idsOfSomething
) {
    // 业务代码
}

解决建议 #

1. 用标准安全Scheme配置认证头 #

Authorization是标准的HTTP认证请求头，OpenAPI UI会对这类头做特殊处理，建议通过安全Scheme声明来配置，而非普通@Parameter：

@OpenAPIDefinition(
    security = @SecurityRequirement(name = "bearerAuth")
)
@SecurityScheme(
    name = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT"
)
@RestController
public class YourController {
    @GetMapping(value = "somevalue")
    @Operation(summary = "Get something")
    @Parameter(
        name = "code",
        description = "Code",
        required = true,
        in = ParameterIn.HEADER,
        schema = @Schema(allowableValues = {"A", "B", "C", "D"})
    )
    public List<IIRDto> getII(
        @Parameter(required = true) @NotNull @RequestParam List<Long> idsOfSomething,
        @RequestHeader("Authorization") String authorization
    ) {
        // 业务代码
    }
}

配置后，OpenAPI UI会显示专门的认证输入框，输入的Token会自动以Authorization: Bearer {token}格式发送请求。

2. 调整OpenAPI UI配置 #

如果不想用安全Scheme，可通过配置禁用UI对Authorization头的默认拦截，在application.yml中添加：

springdoc:
  swagger-ui:
    persist-authorization: true

该配置会让UI保留用户输入的认证信息，确保Authorization头被正常传递。

3. 检查CORS配置 #

确认后端CORS配置允许Authorization头跨域传递，Spring Boot全局CORS配置示例：

@Configuration
public class CorsConfig {
    @Bean
    public CorsFilter corsFilter() {
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        CorsConfiguration config = new CorsConfiguration();
        config.addAllowedOriginPattern("*"); // 根据实际业务调整允许的域名
        config.addAllowedHeader("*");
        config.addAllowedMethod("*");
        config.setAllowCredentials(true);
        source.registerCorsConfiguration("/**", config);
        return new CorsFilter(source);
    }
}

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