如何在Java中为Swagger所有请求添加全局version请求头？

当然可以！在旧项目集成Swagger时，完全不用逐个修改大量接口定义，也不需要直接编辑JSON/YAML文件，我们可以通过Java代码全局配置的方式，给所有Swagger接口统一加上version请求头。下面针对两种主流的Swagger生态（Springfox Swagger2、SpringDoc OpenAPI3）给出具体实现：

方案1：适配Springfox Swagger2（旧版Swagger，常见于Spring Boot 2.x及之前项目） #

这种方案通过Docket的全局参数配置，给所有接口自动注入version请求头：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.Parameter;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.spi.DocumentationType;

import java.util.Collections;
import java.util.List;

@Configuration
public class SwaggerGlobalConfig {

    @Bean
    public Docket apiDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 保留你的其他Swagger配置（比如apiInfo、select()扫描接口等）
                .globalOperationParameters(getGlobalVersionHeader());
    }

    // 构建全局version请求头
    private List<Parameter> getGlobalVersionHeader() {
        Parameter versionHeader = new ParameterBuilder()
                .name("version")
                .description("客户端App版本号，用于后端版本校验")
                .modelRef(new ModelRef("string")) // 指定参数类型为字符串
                .parameterType("header") // 标记参数位置为请求头
                .required(true) // 根据你的过滤器规则设置是否必填
                .build();
        return Collections.singletonList(versionHeader);
    }
}

配置完成后，Swagger UI中所有接口的请求参数区都会自动出现version输入框，测试接口时输入对应版本号，请求会自动携带该头信息，完美满足后端过滤器的校验要求。如果需要给version设置固定默认值（比如测试环境统一用1.0.0），只需在ParameterBuilder中追加.defaultValue("1.0.0")即可。

方案2：适配SpringDoc OpenAPI3（适用于Spring Boot 3.x或采用OpenAPI3规范的项目） #

如果你的项目已经升级到OpenAPI3规范，通过构建OpenAPI实例来全局添加请求头：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.parameters.HeaderParameter;
import io.swagger.v3.oas.models.parameters.Parameter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiGlobalConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        // 构建version请求头参数
        Parameter versionHeader = new HeaderParameter()
                .name("version")
                .description("客户端App版本号，用于后端版本校验")
                .required(true)
                .schema(new io.swagger.v3.oas.models.Schema<String>().type("string"));

        return new OpenAPI()
                // 保留你的其他OpenAPI配置（比如info、servers等）
                .addParametersItem(versionHeader);
    }
}

这个配置会让所有OpenAPI接口自动继承version请求头，Swagger UI的表现和方案1一致，无需手动修改任何接口定义。

额外说明 #

• 两种方案都不需要修改原有接口代码或Swagger的JSON/YAML配置文件，完全通过Java配置类实现全局注入；
• 如果你的过滤器对version格式有特定要求（比如语义化版本x.y.z），可以在description中补充说明，方便测试人员输入；
• 若需要动态调整version值（比如从配置文件读取），可以直接在配置类中注入@Value("${swagger.version.default}")来替换固定值。

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