ASP.NET中HttpGet用FromQuery传复杂对象的Swagger显示问题

ASP.NET Core的模型绑定系统和Swagger（OpenAPI）的文档生成逻辑，对类的属性和字段采用了不同处理规则：

• 带get/set的属性是.NET推荐的封装方式，框架默认支持查询字符串扁平化绑定——会自动把复杂对象的属性拆成独立的查询参数，Swagger会跟着这个规则生成文档，所以显示成三个单独参数，也不会把MyParam加入Schema。
• 对于字段，模型绑定系统默认不会自动拆解映射，Swagger会把整个对象当成单个参数，要求传入JSON格式的值，同时把MyParam类加入Schema。

想用属性实现和字段一样的Swagger表现，需要调整模型绑定逻辑或Swagger的文档生成规则，以下是两种可行方案：

方案1：自定义模型绑定器，强制从查询字符串绑定JSON对象 #

这个方案让框架直接从查询参数里读取JSON字符串，反序列化为MyParam对象，同时Swagger会自动识别为单个对象参数：

1. 实现自定义模型绑定器：

public class JsonQueryModelBinder : IModelBinder
{
    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        if (bindingContext == null)
            throw new ArgumentNullException(nameof(bindingContext));

        var paramName = bindingContext.ModelName;
        var valueProviderResult = bindingContext.ValueProvider.GetValue(paramName);

        if (valueProviderResult == ValueProviderResult.None)
            return Task.CompletedTask;

        bindingContext.ModelState.SetModelValue(paramName, valueProviderResult);

        try
        {
            var json = valueProviderResult.FirstValue;
            var model = JsonSerializer.Deserialize(json, bindingContext.ModelType, new JsonSerializerOptions
            {
                PropertyNameCaseInsensitive = true
            });

            bindingContext.Result = ModelBindingResult.Success(model);
        }
        catch (JsonException ex)
        {
            bindingContext.ModelState.TryAddModelError(paramName, $"JSON格式无效：{ex.Message}");
        }

        return Task.CompletedTask;
    }
}

2. 创建模型绑定提供器：

public class JsonQueryModelBinderProvider : IModelBinderProvider
{
    public IModelBinder GetBinder(ModelBinderProviderContext context)
    {
        if (context == null)
            throw new ArgumentNullException(nameof(context));

        if (context.Metadata.ModelType == typeof(MyParam))
            return new BinderTypeModelBinder(typeof(JsonQueryModelBinder));

        return null;
    }
}

3. 在Program.cs里注册这个提供器：

builder.Services.AddControllers(options =>
{
    options.ModelBinderProviders.Insert(0, new JsonQueryModelBinderProvider());
});

4. 保持MyParam的属性定义不变，此时Swagger会把myParam显示为单个参数，要求传入JSON，同时生成MyParam的Schema。

方案2：配置Swagger强制显示对象参数（需配合绑定逻辑） #

如果只需要Swagger文档显示成单个对象参数，同时确保能正确绑定JSON格式的查询值，可以修改Swagger的Schema生成逻辑：

1. 在Swagger配置中添加操作过滤器：

builder.Services.AddSwaggerGen(c =>
{
    c.OperationFilter<ForceObjectParameterFilter>();
});

public class ForceObjectParameterFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var param = operation.Parameters.FirstOrDefault(p => p.Name == "myParam");
        if (param != null && context.ApiDescription.ParameterDescriptions.Any(p => p.Name == "myParam" && p.Type == typeof(MyParam)))
        {
            param.Schema = context.SchemaGenerator.GenerateSchema(typeof(MyParam), context.SchemaRepository);
            param.Content = new Dictionary<string, OpenApiMediaType>
            {
                ["application/json"] = new OpenApiMediaType
                {
                    Schema = context.SchemaGenerator.GenerateSchema(typeof(MyParam), context.SchemaRepository)
                }
            };
        }
    }
}

2. 注意：这个方案只修改了Swagger文档的显示，要让实际请求能正确绑定，还是需要配合方案1的自定义模型绑定器，否则直接传入JSON字符串会绑定失败。

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