ASP.NET Core 5 Web API：单POST请求传递员工列表与IFormFile的配置

要实现Swagger显示可重复的员工信息输入块（包含姓名和头像），需要调整Swagger的Schema渲染逻辑，同时确保ASP.NET Core能正确绑定表单数据，具体步骤如下：

1. 修正ViewModel的语法错误 #

先把ViewModel里多余的分号去掉（否则会编译失败）：

public class EmployeeRequestViewModel
{
    public string EmployeeName { get; set; }
    public IFormFile ProfileImage { get; set; }
}

public class CreateCompanyRequestViewModel
{
    public string CompanyName { get; set; }
    public IFormFile CompanyLogo { get; set; }
    public List<EmployeeRequestViewModel> Employees { get; set; } = new List<EmployeeRequestViewModel>();
}

2. 添加Swagger自定义Schema过滤器 #

Swagger默认会把List类型渲染成嵌套的JSON结构，我们需要自定义过滤器让它识别为可重复的表单组：

创建一个Schema过滤器类：

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

public class RepeatableEmployeeFormFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 只处理EmployeeRequestViewModel的列表类型
        if (context.Type == typeof(List<EmployeeRequestViewModel>))
        {
            // 清空默认生成的属性
            schema.Properties.Clear();
            // 设置为数组类型，定义单条员工的表单字段
            schema.Type = "array";
            schema.Items = new OpenApiSchema
            {
                Type = "object",
                Properties = new Dictionary<string, OpenApiSchema>
                {
                    ["EmployeeName"] = new OpenApiSchema { Type = "string", Description = "员工姓名" },
                    ["ProfileImage"] = new OpenApiSchema { Type = "string", Format = "binary", Description = "员工头像" }
                },
                // 如果EmployeeName是必填项，添加到Required集合
                Required = new HashSet<string> { "EmployeeName" }
            };
            // 添加扩展标记，告诉Swagger这是可重复的表单块
            schema.Extensions.Add("x-ms-form-extension", new OpenApiObject
            {
                ["repeatable"] = new OpenApiBoolean(true)
            });
        }
    }
}

3. 注册Swagger过滤器 #

在Program.cs（或Startup.cs）的Swagger配置中注册这个过滤器：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "公司管理API", Version = "v1" });
    // 注册自定义过滤器
    c.SchemaFilter<RepeatableEmployeeFormFilter>();
});

4. 测试表单提交格式 #

配置完成后，Swagger会显示可添加的员工输入块，提交时表单字段名需要遵循ASP.NET Core的列表绑定规则：

• 第一条员工：Employees[0].EmployeeName、Employees[0].ProfileImage
• 第二条员工：Employees[1].EmployeeName、Employees[1].ProfileImage
• 以此类推

ASP.NET Core会自动将这些字段绑定到CreateCompanyRequestViewModel的Employees列表中。

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