Swagger中FromForm模式HttpPost请求List参数为空问题求助

方案1：手动使用索引式表单字段传递集合 #

在Swagger的表单界面中，不要在Details输入框中填写JSON数组，而是通过"Add additional parameter"按钮添加以下格式的键值对：

• 键：Details[0].PropertyName，值：第一个Detail对象的PropertyName值
• 键：Details[0].PropertyValue，值：第一个Detail对象的PropertyValue值
• 键：Details[1].PropertyName，值：第二个Detail对象的PropertyName值
• 键：Details[1].PropertyValue，值：第二个Detail对象的PropertyValue值

ASP.NET Core的FromForm模型绑定会自动识别这种索引格式的字段，将其绑定到List<Detail>集合中。

方案2：自定义Swagger Schema过滤器优化UI体验 #

如果不想手动输入索引字段，可以通过自定义Swagger的Schema过滤器，让Swagger UI自动生成集合元素的输入项：

1. 创建Schema过滤器类：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Reflection;

public class FormCollectionSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 针对List<T>类型的复杂对象集合处理
        if (context.Type.IsGenericType && context.Type.GetGenericTypeDefinition() == typeof(List<>))
        {
            var itemType = context.Type.GetGenericArguments()[0];
            // 仅处理非原始类型的集合元素
            if (!itemType.IsPrimitive && !typeof(string).IsAssignableFrom(itemType))
            {
                schema.Type = "object";
                schema.Properties.Clear();
                schema.Example = null;

                // 生成两个示例元素的字段（可根据需要调整数量）
                for (int i = 0; i < 2; i++)
                {
                    var properties = itemType.GetProperties(BindingFlags.Public | BindingFlags.Instance);
                    foreach (var prop in properties)
                    {
                        var propSchema = context.SchemaGenerator.GenerateSchema(prop.PropertyType, context.SchemaRepository);
                        schema.Properties.Add($"Details[{i}].{prop.Name}", propSchema);
                    }
                }
            }
        }
    }
}

2. 在Swagger配置中注册该过滤器：

builder.Services.AddSwaggerGen(c =>
{
    // 其他Swagger配置...
    c.SchemaFilter<FormCollectionSchemaFilter>();
});

重新启动项目后，Swagger UI会为Details集合显示多个带索引的输入框，直接填写对应值即可完成绑定。

方案3：临时改用JSON字符串手动反序列化（不推荐） #

如果以上方案都无法快速实施，可以临时修改实体类，将Details改为string类型，然后在控制器中手动反序列化：

修改DocumentAddRequest：

public class DocumentAddRequest
{
    public string Name { get; set; }
    public IFormFile File { get; set; }
    public string Details { get; set; } // 改为string类型
}

在控制器中处理：

using Newtonsoft.Json;

[HttpPost]
public IActionResult AddDocument([FromForm] DocumentAddRequest request)
{
    var details = JsonConvert.DeserializeObject<List<Detail>>(request.Details);
    // 后续业务逻辑...
}

此时在Swagger的Details输入框中填写JSON数组即可，但该方案需要修改实体结构，仅作为临时应急方案。

问题原因 #

FromForm模型绑定依赖表单键值对的格式，而Swagger默认对复杂集合类型会生成JSON输入框，ASP.NET Core无法直接将JSON字符串解析为List<Detail>集合，必须使用索引式的表单字段格式才能正确绑定。

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