如何在ASP.NET Core 3.1中实现OpenAPI文档中定义的深度对象模型绑定？

我之前也碰到过类似的场景——ASP.NET Core 3.1默认的模型绑定和Swagger（OpenAPI）对product[name]这种嵌套风格的查询参数支持确实不太友好，下面给你分两步搞定：先让模型能正确绑定参数，再让OpenAPI文档显示正确的参数格式。

一、实现深度对象的模型绑定 #

方法1：用特性直接指定参数映射（最简方案） #

不需要写复杂的绑定器，直接给ProductQuery的属性加上[FromQuery]特性，指定对应的嵌套查询键即可：

public class ProductQuery: IRequest<IEnumerable<ProductDto>>
{
    [FromQuery(Name = "product[name]")]
    public string Name {get; set;}

    [FromQuery(Name = "product[type]")]
    public string Type {get; set;}
}

这样ASP.NET Core就能自动把product[name]的值绑定到Name属性，product[type]绑定到Type属性，完全不用改控制器代码。

方法2：自定义模型绑定器（通用场景） #

如果有很多类似的深度对象参数，写一个通用的绑定器更高效：

public class DeepObjectModelBinder<T> : IModelBinder where T : new()
{
    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        if (bindingContext == null)
            throw new ArgumentNullException(nameof(bindingContext));

        var modelPrefix = bindingContext.ModelName;
        var queryParams = bindingContext.HttpContext.Request.Query;
        var model = new T();
        var properties = typeof(T).GetProperties();

        foreach (var prop in properties)
        {
            var queryKey = $"{modelPrefix}[{prop.Name.ToLower()}]";
            if (queryParams.TryGetValue(queryKey, out var value))
            {
                prop.SetValue(model, value.ToString());
            }
        }

        bindingContext.Result = ModelBindingResult.Success(model);
        return Task.CompletedTask;
    }
}

然后给ProductQuery标记绑定器：

[ModelBinder(BinderType = typeof(DeepObjectModelBinder<ProductQuery>))]
public class ProductQuery: IRequest<IEnumerable<ProductDto>>
{
    public string Name {get; set;}
    public string Type {get; set;}
}

二、让OpenAPI文档正确显示深度参数 #

默认Swagger会把ProductQuery的属性显示为平级的Name、Type参数，需要调整配置让它显示成product[name]格式：

方法1：手动标注Swagger参数（简单场景） #

直接在控制器的Action上用[SwaggerParameter]指定参数名称：

[HttpGet]
[SwaggerParameter("product[name]", "产品名称", Required = false)]
[SwaggerParameter("product[type]", "产品类型", Required = false)]
public async Task<IActionResult> Get([FromQuery]ProductQuery productQuery)
{
    var response = await _mediator.Send(productQuery);
    return Ok(response);
}

方法2：自定义Swagger操作过滤器（通用场景） #

如果有多个深度对象参数，写一个过滤器自动转换参数名称：

public class DeepObjectSwaggerFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var paramsToRemove = new List<OpenApiParameter>();
        var paramsToAdd = new List<OpenApiParameter>();

        foreach (var param in operation.Parameters)
        {
            // 找到属于ProductQuery的参数
            var paramDesc = context.ApiDescription.ParameterDescriptions
                .FirstOrDefault(p => p.Name == param.Name);
            if (paramDesc?.ParameterType == typeof(ProductQuery))
            {
                paramsToRemove.Add(param);
                // 构造深度参数名，比如product[name]
                var deepParamName = $"product[{param.Name.ToLower()}]";
                paramsToAdd.Add(new OpenApiParameter
                {
                    Name = deepParamName,
                    In = ParameterLocation.Query,
                    Description = param.Description,
                    Required = param.Required,
                    Schema = param.Schema
                });
            }
        }

        // 替换原有参数
        foreach (var p in paramsToRemove) operation.Parameters.Remove(p);
        foreach (var p in paramsToAdd) operation.Parameters.Add(p);
    }
}

然后在Startup.cs中注册这个过滤器：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    c.OperationFilter<DeepObjectSwaggerFilter>(); // 添加过滤器
});

这样Swagger文档里就会正确显示product[name]和product[type]的查询参数了。

总结 #

如果只是单个模型的简单需求，用[FromQuery(Name = "...")]加手动Swagger标注最省心；如果是多个深度对象的通用场景，自定义绑定器和Swagger过滤器会更高效。

内容的提问来源于stack exchange，提问作者J. Viégas