Spring Boot 3+Swagger/OpenAPI 3如何全局定义请求头X-example

针对你需要在所有接口中统一添加必填请求头X-example的需求，以下是适配springdoc-openapi-starter-webmvc-ui 2.2.0版本的两种可行方案，无需在每个接口重复配置：

方案1：通过OpenApiCustomizer实现全局参数注入 #

创建配置类，使用OpenApiCustomizer遍历所有API路径和操作，统一添加请求头参数：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.parameters.Parameter;
import org.springdoc.core.customizers.OpenApiCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiGlobalConfig {

    @Bean
    public OpenApiCustomizer globalHeaderCustomizer() {
        return openApi -> {
            // 定义全局请求头参数
            Parameter exampleHeader = new Parameter()
                    .name("X-example")
                    .required(true)
                    .in("header")
                    .description("全局必填请求头参数");

            // 为所有路径下的所有操作添加该参数
            openApi.getPaths().values().forEach(pathItem ->
                    pathItem.readOperations().forEach(operation ->
                            operation.addParametersItem(exampleHeader)
                    )
            );
        };
    }
}

方案2：通过@OpenAPIDefinition的全局参数引用 #

利用OpenAPI的组件定义+全局引用机制，先在组件中声明参数，再全局应用到所有接口：

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Components;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.context.annotation.Configuration;

@OpenAPIDefinition(
        info = @Info(title = "资产管理API", version = "v1"),
        components = @Components(
                // 定义可复用的参数组件
                parameters = {
                        @Parameter(
                                name = "X-example",
                                in = ParameterIn.HEADER,
                                required = true,
                                description = "全局必填请求头"
                        )
                }
        ),
        // 全局引用该参数，自动应用到所有接口
        parameters = {
                @Parameter(ref = "#/components/parameters/X-example")
        }
)
@Configuration
public class OpenApiGlobalConfig {
}

两种方案均无需修改现有接口代码，配置完成后启动项目，Swagger UI中所有接口都会自动显示X-example必填请求头。

问题表述优化建议 #

1. 补充例外场景：如果存在不需要该请求头的接口，可以在问题中说明，方便提供更精准的排除方案（比如通过@Parameter(hidden = true)覆盖全局配置）。
2. 强化痛点描述：将"有10余个接口"改为"维护10+接口时重复编写相同配置，代码冗余且易出错"，更清晰地传递需求价值。
3. 明确已尝试的无效方案：可以具体说明找到的旧版方案类型（比如基于Springfox的@ApiImplicitParams全局配置），帮助回答者快速排除不适配的方案。

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