ASP.NET Core中通过Header参数传递JSON对象实现API请求控制的异常问题排查

你遇到的问题核心在于Swagger UI对Header中复杂对象参数的默认序列化行为。当你定义Header参数为DmsRequestModel对象类型时，Swagger UI会采用form风格的序列化方式（把对象的键值对用逗号拼接），而不是将其序列化为JSON字符串，这就是为什么curl请求里的dmsFilter变成了逗号分隔的字符串。

为什么会这样？ #

HTTP Header的设计初衷是传递简单的键值对，而非复杂的结构化数据。Swagger UI的默认逻辑认为Header参数应该是简单类型（字符串、数字等），所以遇到对象类型时，会自动将其拆解为逗号分隔的键值对，这并不是你期望的JSON格式。

解决方案1：将Header参数改为字符串类型（推荐） #

最直接的修复方式是把dmsFilter定义为字符串类型，让用户输入JSON格式的字符串，然后在后端将其反序列化为DmsRequestModel对象。修改你的DmsFilterOperationFilter：

public class DmsFilterOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if(context.MethodInfo.GetCustomAttribute(typeof(DmsFilter), true) is null) return;
        operation.Parameters ??= new List<OpenApiParameter>();
        
        // 直接使用string类型的Schema，而非生成对象Schema
        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "dmsFilter",
            Description = "Configure requests to Indicium here. Input a valid JSON string (e.g. {\"prefilter\":\"authorized\",\"orderBy\":\"planned_starting_date_time asc\"})",
            In = ParameterLocation.Header,
            Required = false,
            Schema = new OpenApiSchema { Type = "string" }
        });
    }
}

然后在接口方法中，接收这个字符串并反序列化：

[HttpGet("all")]
[DmsFilter]
public IActionResult GetAll([FromHeader(Name = "dmsFilter")] string dmsFilterJson)
{
    DmsRequestModel dmsFilter = null;
    if (!string.IsNullOrEmpty(dmsFilterJson))
    {
        try
        {
            dmsFilter = JsonSerializer.Deserialize<DmsRequestModel>(dmsFilterJson);
        }
        catch (JsonException ex)
        {
            return BadRequest("Invalid JSON format in dmsFilter header");
        }
    }
    
    // 后续逻辑...
}

这样Swagger UI会显示一个文本输入框，用户可以直接粘贴JSON字符串，curl请求也会正确传递JSON格式的Header值。

解决方案2：自定义Swagger UI的序列化行为（复杂） #

如果你坚持要让Swagger UI自动将对象序列化为JSON字符串，需要修改Swagger UI的配置。你可以通过注入自定义的JavaScript来覆盖默认的参数序列化逻辑：

在Program.cs中添加Swagger UI的自定义脚本：

app.UseSwaggerUI(options =>
{
    options.InjectJavascript("/swagger-ui/custom-header-serializer.js");
});

然后创建wwwroot/swagger-ui/custom-header-serializer.js文件，编写逻辑将对象参数序列化为JSON字符串：

const originalBuildRequest = window.ui.buildRequest;
window.ui.buildRequest = (operation, schema, options) => {
    const request = originalBuildRequest(operation, schema, options);
    
    // 找到dmsFilter Header参数
    const dmsFilterHeader = request.headers.find(h => h.name === 'dmsFilter');
    if (dmsFilterHeader && typeof dmsFilterHeader.value === 'object') {
        // 将对象序列化为JSON字符串
        dmsFilterHeader.value = JSON.stringify(dmsFilterHeader.value);
    }
    
    return request;
};

这种方式需要维护前端脚本，复杂度较高，除非有特殊需求，否则不推荐。

替代方案：更优雅的参数传递方式 #

Header传递JSON确实不是HTTP的常规用法，还有几种更合适的方案可以实现你的需求：

• 拆分多个Query参数：把DmsRequestModel的每个属性作为单独的Query参数，比如?filter=xxx&orderBy=xxx&includeFiles=true。这种方式更符合RESTful风格，也更容易被客户端理解和使用，Swagger UI的支持也更完善。
• 使用POST请求的Request Body：如果你的接口可以改为POST（比如查询操作也允许POST），可以把过滤配置放在Request Body中，这是传递结构化数据的标准方式。
• 自定义Query参数的复合格式：比如用filter[prefilter]=authorized&filter[orderBy]=xxx这样的格式，后端可以直接绑定到DmsRequestModel对象（ASP.NET Core原生支持这种绑定方式）。

总结来说，最推荐的是解决方案1（将Header参数改为字符串类型），或者考虑替代方案1（拆分Query参数），这两种方式都能避免Swagger UI的序列化问题，同时符合HTTP的最佳实践。

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