Swagger UI调用Azure App Services接口缺失ZUMO参数问题求助

一、Swagger UI全局添加ZUMO-API-VERSION参数 #

方式1：添加为请求头参数 #

在Swagger配置代码中，通过自定义操作过滤器全局注入请求头参数：

builder.Services.AddSwaggerGen(c =>
{
    // 保留原有Swagger配置
    c.OperationFilter<AddZumoApiVersionHeaderFilter>();
});

// 自定义操作过滤器类
public class AddZumoApiVersionHeaderFilter : 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,
            Required = true, // 可根据实际需求调整是否必填
            Schema = new OpenApiSchema { Type = "string", Default = new OpenApiString("3.0.0") }
        });
    }
}

方式2：添加为查询字符串参数 #

若需要以查询参数形式传递，只需修改过滤器中参数的位置配置：

public class AddZumoApiVersionQueryFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        operation.Parameters ??= new List<OpenApiParameter>();
        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "ZUMO-API-VERSION",
            In = ParameterLocation.Query,
            Required = true,
            Schema = new OpenApiSchema { Type = "string", Default = new OpenApiString("3.0.0") }
        });
    }
}

注册时替换对应的过滤器即可。

二、解决控制器路由配置问题 #

路由模板不支持直接写入查询参数（带?的语法），正确配置方式如下：

1. 在Action方法中声明查询参数 #

如果需要在接口中接收该参数（即使仅做透传），直接在Action方法参数上标记[FromQuery]：

[ApiController]
[Route("api/[controller]")]
public class TodoItemsController : ControllerBase
{
    [HttpGet]
    public IActionResult GetItems([FromQuery(Name = "ZUMO-API-VERSION")] string zumoApiVersion = "3.0.0")
    {
        // 业务逻辑实现
        return Ok();
    }
}

这种方式不会触发路由模板异常，同时Swagger会自动识别该参数。

2. 用中间件自动添加参数（无需在Action中声明） #

如果不需要在Action中处理该参数，仅需透传给Azure App Services，可通过中间件全局自动添加：

app.Use(async (context, next) =>
{
    // 自动添加查询参数
    if (!context.Request.Query.ContainsKey("ZUMO-API-VERSION"))
    {
        context.Request.QueryString = context.Request.QueryString.Add("ZUMO-API-VERSION", "3.0.0");
    }
    // 如需添加请求头，替换为以下代码
    // if (!context.Request.Headers.ContainsKey("ZUMO-API-VERSION"))
    // {
    //     context.Request.Headers.Add("ZUMO-API-VERSION", "3.0.0");
    // }
    await next();
});

将该中间件注册在Swagger中间件之前，确保参数在请求转发前被注入。

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