ASP.NET Core配置Swagger UI添加ZUMO-API-VERSION请求头遇加载问题

你的问题出在SwaggerHeader类的错误配置上，导致Swagger无法正确生成请求头参数，进而请求卡住。以下是修正后的完整方案：

1. 修正SwaggerHeader过滤器实现 #

你的代码存在两个关键错误：

• 请求头名称错误包含等号=，正确名称应为ZUMO-API-VERSION
• 未指定参数位置为请求头（Header），Swagger默认会将参数当作Query参数处理，不符合接口要求

修正后的代码：

public class SwaggerHeader : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        operation.Parameters ??= new List<OpenApiParameter>();

        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "ZUMO-API-VERSION",
            In = ParameterLocation.Header, // 指定参数位置为请求头
            Description = "API版本号，固定值为3.0.0",
            Required = true,
            Schema = new OpenApiSchema
            {
                Type = "string",
                Default = new OpenApiString("3.0.0") // 设置默认值，Swagger UI自动填充
            }
        });
    }
}

2. 注册Swagger过滤器 #

在AddSwaggerGen中添加过滤器注册，确保Swagger生成文档时应用该配置：

builder.Services.AddSwaggerGen(c => {
    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo()
    {
        Title = "Skillbased Middleware API Info",
        Version = "v1"
    });
    // 注册自定义请求头过滤器
    c.OperationFilter<SwaggerHeader>();
});

3. 保留原有Swagger中间件配置 #

你的中间件配置无需修改，保持如下即可：

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Company API Testing v1");
});

完成配置后重启应用，Swagger UI的每个接口都会自动添加ZUMO-API-VERSION请求头输入框，且默认填充3.0.0，发起请求时会自动携带该请求头，即可正常调用接口。

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