使用Swagger3（springdoc-openapi-ui）添加全局请求头参数不显示问题排查

核心问题分析 #

你当前的代码存在两个关键问题，导致全局请求头未在Swagger控制台显示：

1. addHeaders的误用：addHeaders方法是用来定义响应头的，不是请求头，所以你定义的myHeader2会被识别为接口响应返回的头，不会出现在请求参数区域。
2. 未关联全局参数到API操作：虽然你在Components中定义了myHeader1请求参数，但没有将这个参数绑定到任何API操作（或全局所有操作）上，Swagger UI不会自动加载未关联的组件定义。

修复方案 #

方案1：全局添加普通请求头（推荐给所有接口统一加请求头）

通过OpenApiCustomiser实现对所有API操作批量添加请求头，修改你的配置类如下：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.parameters.Parameter;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.media.StringSchema;
import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .components(new Components()
                        .addSecuritySchemes("basicScheme",
                                new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic")))
                .info(new Info().title("eWallet API Sandbox").description("eWallet API Sandbox").version("v1.0")
                        .contact(new Contact().name("WOW Finstack").url("https://wowdigital.ai/")
                                .email("info@wowdigital.ai"))
                        .termsOfService("WOW Finstack").license(new License().name("License").url("#")));
    }

    // 全局添加请求头的自定义器
    @Bean
    public OpenApiCustomiser globalRequestHeaderCustomiser() {
        return openApi -> openApi.getPaths().values().stream()
                .flatMap(pathItem -> pathItem.readOperations().stream())
                .forEach(operation -> {
                    // 添加myHeader1请求头
                    operation.addParametersItem(
                            new Parameter().in("header").schema(new StringSchema())
                                    .name("myHeader1").description("自定义全局请求头1").required(false)
                    );
                    // 如果需要添加第二个请求头，直接追加即可
                    operation.addParametersItem(
                            new Parameter().in("header").schema(new StringSchema())
                                    .name("myHeader2").description("自定义全局请求头2").required(false)
                    );
                });
    }
}

如果希望复用Components中定义的参数（避免重复代码），可以先在Components中定义参数，再在自定义器中引用：

// 在customOpenAPI的components中添加参数定义
.addParameters("myHeader1", 
        new Parameter().in("header").schema(new StringSchema()).name("myHeader1").description("自定义全局请求头1"))

// 在globalRequestHeaderCustomiser中引用
operation.addParametersItem(new Parameter().$ref("#/components/parameters/myHeader1"));

方案2：通过SecurityScheme绑定认证类请求头

如果你的全局请求头是用于身份认证的（比如自定义API Key），可以用SecurityScheme的方式全局绑定：

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .components(new Components()
                    .addSecuritySchemes("basicScheme",
                            new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic"))
                    // 定义自定义认证头的SecurityScheme
                    .addSecuritySchemes("myHeaderAuth",
                            new SecurityScheme().type(SecurityScheme.Type.APIKEY)
                                    .in(SecurityScheme.In.HEADER).name("myHeader1").description("认证请求头")))
            .info(new Info().title("eWallet API Sandbox").description("eWallet API Sandbox").version("v1.0")
                    .contact(new Contact().name("WOW Finstack").url("https://wowdigital.ai/")
                            .email("info@wowdigital.ai"))
                    .termsOfService("WOW Finstack").license(new License().name("License").url("#")))
            // 全局应用这个认证头
            .addSecurityItem(new SecurityRequirement().addList("myHeaderAuth"));
}

验证说明 #

修改配置后重启项目，访问Swagger UI（默认路径/swagger-ui.html），就能看到所有接口的请求参数区域已经显示你添加的全局请求头了。

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