带FromForm属性与数组属性的Swagger JSON生成失败问题排查

问题根源 #

当使用[FromForm]绑定包含List<CustomKVP>这类复杂对象集合的DTO时，Swagger生成OpenAPI规范会触发验证错误。原因是OpenAPI对表单参数的集合类型处理规则与JSON请求体不同：表单参数默认只支持简单类型集合（如List<string>），而复杂对象集合的表单提交格式（如AdditionalInput[0].Name=xxx）无法被Swagger默认的Schema生成逻辑正确映射，导致Schema结构不符合OpenAPI规范要求。

可行解决方案 #

方案1：拆分复杂集合为独立的FromQuery参数（简单直接） #

把AdditionalInput从DTO中拆分出来，单独用[FromQuery]绑定，让Swagger能正确识别集合类型：

// 修改InputClass，移除AdditionalInput属性
public class InputClass
{
    public IFormFile File { get; set; }
    public string Name { get; set; }
}

// 修改Action方法
[HttpPost]
[Route("abc/{id}/createFile")]
[SwaggerOperation(OperationId = "createFile")]
public async Task<IActionResult> CreateFileAsync(
    [FromRoute] string id, 
    [FromForm] InputClass inputClass,
    [FromQuery] List<CustomKVP> additionalInput)
{
    // 业务逻辑
}

提交请求时，复杂集合参数需以additionalInput[0].Name=xxx&additionalInput[0].Value=yyy的格式传递。

方案2：自定义Swagger Schema过滤器修复生成逻辑 #

通过自定义Schema过滤器，调整Swagger对FromForm绑定的复杂集合的Schema生成规则：

public class FormCollectionSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 只处理FromForm绑定的参数
        if (context.ParameterInfo?.GetCustomAttributes(typeof(FromFormAttribute), false).Any() != true)
            return;

        foreach (var (propName, propSchema) in schema.Properties.ToList())
        {
            // 识别数组类型且元素是引用类型的属性
            if (propSchema.Type == "array" && propSchema.Items?.Reference != null)
            {
                // 替换为直接生成元素的对象Schema，符合表单参数规则
                var itemSchema = context.SchemaGenerator.GenerateSchema(
                    context.SchemaRepository.Schemas[propSchema.Items.Reference.Id].ClrType, 
                    context.SchemaRepository);
                propSchema.Items = itemSchema;
                propSchema.Items.Reference = null;
            }
        }
    }
}

然后在Swagger配置中注册该过滤器：

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

方案3：手动解析IFormCollection（最灵活） #

放弃自动绑定DTO，直接通过IFormCollection手动解析表单数据，完全绕开Swagger的Schema生成问题：

[HttpPost]
[Route("abc/{id}/createFile")]
[SwaggerOperation(OperationId = "createFile")]
public async Task<IActionResult> CreateFileAsync(
    [FromRoute] string id, 
    [FromForm] IFormFile file,
    [FromForm] string name,
    [FromForm] IFormCollection form)
{
    // 手动解析AdditionalInput集合
    var additionalInput = new List<CustomKVP>();
    var index = 0;
    while (form.TryGetValue($"AdditionalInput[{index}].Name", out var nameValue) 
           && form.TryGetValue($"AdditionalInput[{index}].Value", out var valueValue))
    {
        additionalInput.Add(new CustomKVP
        {
            Name = nameValue,
            Value = valueValue
        });
        index++;
    }

    // 后续业务逻辑
}

方案4：将复杂集合转为JSON字符串传递（兼容现有DTO结构） #

把DTO中的AdditionalInput改为字符串类型，接收JSON格式的集合数据，在Action中手动反序列化：

// 修改InputClass
public class InputClass
{
    public IFormFile File { get; set; }
    public string Name { get; set; }
    public string AdditionalInputJson { get; set; }
}

// 修改Action方法
[HttpPost]
[Route("abc/{id}/createFile")]
[SwaggerOperation(OperationId = "createFile")]
public async Task<IActionResult> CreateFileAsync(
    [FromRoute] string id, 
    [FromForm] InputClass inputClass)
{
    // 反序列化JSON字符串为集合
    var additionalInput = JsonSerializer.Deserialize<List<CustomKVP>>(inputClass.AdditionalInputJson);
    
    // 后续业务逻辑
}

提交请求时，AdditionalInputJson参数传入[{"Name":"xxx","Value":"yyy"}]格式的JSON字符串即可。

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