ASP.NET Core Web API中Swagger未正确展示List类型参数问题

问题根源 #

Swagger UI默认对multipart/form-data格式下的**嵌套复杂类型列表（包含IFormFile）**支持不足，无法自动生成对应的文件上传控件，只能显示JSON格式的字符串输入框。

解决方案 #

1. 自定义Swagger SchemaFilter修复显示 #

通过自定义ISchemaFilter修改Swagger的Schema生成逻辑，让嵌套列表的文件项显示为可识别的表单字段模板：

先创建SchemaFilter类：

public class FormFileListSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 处理单个IFormFile类型
        if (context.Type == typeof(IFormFile) || context.Type == typeof(IFormFile?))
        {
            schema.Type = "string";
            schema.Format = "binary";
            return;
        }

        // 处理包含IFormFile的List<T>类型
        if (!context.Type.IsGenericType || context.Type.GetGenericTypeDefinition() != typeof(List<>)) return;
        
        var itemType = context.Type.GetGenericArguments()[0];
        if (!itemType.GetProperties().Any(p => p.PropertyType == typeof(IFormFile) || p.PropertyType == typeof(IFormFile?))) return;

        // 替换默认JSON示例为表单字段格式
        schema.Type = "object";
        schema.Properties.Clear();
        schema.Example = new OpenApiObject
        {
            ["Files[0].Quality"] = new OpenApiString("1080p"),
            ["Files[0].Season"] = new OpenApiInteger(1),
            ["Files[0].Episode"] = new OpenApiInteger(1),
            ["Files[0].File"] = new OpenApiString("(binary)"),
            ["Files[1].Quality"] = new OpenApiString("720p"),
            ["Files[1].File"] = new OpenApiString("(binary)")
        };
    }
}

然后在Program.cs中注册该Filter：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    c.SchemaFilter<FormFileListSchemaFilter>();
    c.EnableAnnotations(); // 启用注解支持
});

2. 手动处理请求表单绑定 #

如果自动绑定不稳定，可直接从Request.Form读取数据，手动构建模型：

[HttpPost]
[RequestFormLimits(MultipartBodyLengthLimit = 104857600)] // 设置100MB上传限制
public async Task<IActionResult> Add()
{
    var model = new AddMovieViewModel
    {
        Title = Request.Form["Title"],
        ReleasedDate = Request.Form["ReleasedDate"],
        CreatedDate = Request.Form["CreatedDate"],
        IMDB = int.TryParse(Request.Form["IMDB"], out var imdb) ? imdb : null,
        Time = int.TryParse(Request.Form["Time"], out var time) ? time : null,
        Image = Request.Form.Files["Image"],
        Cover = Request.Form.Files["Cover"],
        Summary = Request.Form["Summary"],
        Files = new List<FileViewModel>()
    };

    // 解析Files列表
    if (int.TryParse(Request.Form["Files.Count"], out var fileCount))
    {
        for (var i = 0; i < fileCount; i++)
        {
            var fileItem = new FileViewModel
            {
                Quality = Request.Form[$"Files[{i}].Quality"],
                Season = byte.TryParse(Request.Form[$"Files[{i}].Season"], out var s) ? s : null,
                Episode = byte.TryParse(Request.Form[$"Files[{i}].Episode"], out var e) ? e : null,
                File = Request.Form.Files[$"Files[{i}].File"]
            };
            model.Files.Add(fileItem);
        }
    }

    // 编写业务逻辑
    return Ok();
}

这种方式完全绕过自动绑定限制，确保嵌套文件列表能正确读取。

3. 添加Swagger注解增强提示 #

在模型的Files属性上添加注解，明确提示表单字段命名格式：

public class AddMovieViewModel
{
    // ...其他属性
    [SwaggerSchema(Description = "多个视频文件项，需按格式填写：Files[index].Quality、Files[index].Season、Files[index].Episode，同时上传对应的Files[index].File文件")]
    public List<FileViewModel> Files { get; set; }
}

4. 替代方案：拆分上传请求 #

如果嵌套上传过于复杂，可拆分两步操作：

1. 先提交电影基本信息，返回电影ID
2. 单独调用文件上传接口，传入电影ID和对应的文件、质量、集数等信息

这种方式更简单易维护，适合大文件上传场景。

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