Spring Boot 3中Swagger UI 3无法获取Authorization请求头问题

问题现象 #

基于Spring Boot 3.2.3、Spring 6、Java 17开发的应用，集成Swagger3（springdoc-openapi-starter-webmvc-ui 2.0.3）后，调用/testHeader接口时无法获取Authorization请求头，控制台抛出org.springframework.web.bind.MissingRequestHeaderException异常。

控制台报错信息 #

.w.s.m.s.DefaultHandlerExceptionResolver : Resolved [org.springframework.web.bind.MissingRequestHeaderException: Required request header 'Authorization' for method parameter type String is not present]

控制器代码 #

@RestController
public class TestController {
    @GetMapping("/testHeader")
    public String testHeader(@RequestHeader(value="Authorization") String token){
        return token;
    }
}

pom.xml依赖配置 #

<?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 https://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.2.3</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.test</groupId>
    <artifactId>swagger3-check</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger3-check</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-integration</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.integration</groupId>
            <artifactId>spring-integration-http</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.integration</groupId>
            <artifactId>spring-integration-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.0.3</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

错误截图 #

解决方案 #

原因分析 #

Swagger3（springdoc）默认不会自动携带Authorization请求头到接口调用中，需要手动配置全局参数或声明接口请求头，同时确保请求头传递逻辑正确。

解决步骤 #

1. 配置Swagger全局Authorization参数
   创建Swagger配置类，添加全局请求头认证配置：

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

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .addSecurityItem(new SecurityRequirement().addList("BearerAuth"))
                .components(new io.swagger.v3.oas.models.Components()
                        .addSecuritySchemes("BearerAuth", new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")
                                .bearerFormat("JWT")));
    }
}

该配置会在Swagger UI顶部生成"Authorize"按钮，点击后输入Token，后续调用接口时会自动携带Authorization请求头。

2. 接口层声明请求头（可选）
   若需在接口文档中明确展示Authorization参数，可添加@Parameter注解：

import io.swagger.v3.oas.annotations.Parameter;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class TestController {
    @GetMapping("/testHeader")
    public String testHeader(
            @Parameter(description = "Authorization token", required = true)
            @RequestHeader(value="Authorization") String token){
        return token;
    }
}

3. 验证请求传递
   在Swagger UI中调用接口前，点击"Authorize"按钮，输入格式为Bearer {token}的内容（例如Bearer abc123），再调用/testHeader接口即可正常获取请求头。

4. 第三方工具调用检查
   使用Postman等工具调用时，确保请求头Key为Authorization，Value格式正确；Spring的@RequestHeader默认不区分大小写，无需担心大小写匹配问题。

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