如何在C# .NET Core API中接收Swagger发送的List类型数据

问题原因 #

当使用[FromForm]绑定复杂集合类型（如List<NewDocumentUser>、IEnumerable<Attachment>）时，ASP.NET Core的模型绑定需要遵循索引化的表单字段命名规则，而Swagger默认的提交格式（嵌套JSON）无法被正确解析为集合对象，导致接收为空。

解决方法 #

方法1：使用索引化字段名提交表单 #

手动构造符合模型绑定要求的表单字段，格式如下：

• 对于List<NewDocumentUser> DocumentUsers：
  • DocumentUsers[0].UserName = "用户1"
  • DocumentUsers[0].Email = "user1@example.com"
  • DocumentUsers[1].UserName = "用户2"
  • DocumentUsers[1].Email = "user2@example.com"
• 对于IEnumerable<Attachment> Attachments：
  • Attachments[0].Id = "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  • Attachments[0].Name = "附件1"
  • Attachments[0].ContentType = "application/pdf"

Swagger测试时，在"form-data"模式下按照上述格式添加字段即可。

方法2：配置Swagger支持FromForm集合的正确示例 #

在Program.cs（或Startup.cs）中修改Swagger配置，让它生成符合要求的集合提交模板：

builder.Services.AddSwaggerGen(c =>
{
    // 配置NewDocumentUser集合的Schema
    c.MapType<List<NewDocumentUser>>(() => new OpenApiSchema
    {
        Type = "array",
        Items = new OpenApiSchema
        {
            Type = "object",
            Properties = new Dictionary<string, OpenApiSchema>
            {
                {"userName", new OpenApiSchema { Type = "string", Example = new OpenApiString("testUser") }},
                {"email", new OpenApiSchema { Type = "string", Example = new OpenApiString("test@example.com") }}
            }
        }
    });

    // 配置Attachment集合的Schema
    c.MapType<IEnumerable<Attachment>>(() => new OpenApiSchema
    {
        Type = "array",
        Items = new OpenApiSchema
        {
            Type = "object",
            Properties = new Dictionary<string, OpenApiSchema>
            {
                {"id", new OpenApiSchema { Type = "string", Format = "uuid", Example = new OpenApiString(Guid.NewGuid().ToString()) }},
                {"name", new OpenApiSchema { Type = "string", Example = new OpenApiString("attachment.pdf") }},
                {"contentType", new OpenApiSchema { Type = "string", Example = new OpenApiString("application/pdf") }},
                {"fileDataSize", new OpenApiSchema { Type = "integer", Format = "int64" }}
            }
        }
    });
});

方法3：将集合序列化为JSON字符串传递 #

如果不想调整表单字段格式，可以将集合转为JSON字符串后提交，后端手动反序列化：

1. 前端提交时，将Attachments和DocumentUsers转为JSON字符串，字段名设为AttachmentsJson、DocumentUsersJson
2. 在模型中新增对应字符串属性：

// 原模型新增
public string? AttachmentsJson { get; set; }
public string? DocumentUsersJson { get; set; }

3. 在后端处理时反序列化：

// 在Command处理或Controller中
var attachments = JsonSerializer.Deserialize<IEnumerable<Attachment>>(Document.AttachmentsJson ?? "[]");
var documentUsers = JsonSerializer.Deserialize<List<NewDocumentUser>>(Document.DocumentUsersJson ?? "[]");

额外检查点 #

• 检查集合子模型的属性是否为非可空类型：比如Attachment.Name、NewDocumentUser.UserName都是非可空string，如果提交时未传值，模型绑定会失败导致集合为空。可以改为string?或确保提交所有必填字段。
• 确认CreateDocumentCommand的Data属性包含所有集合字段，没有遗漏定义。

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