Swagger序列化multipart/form-data对象数组不被ASP.NET Core识别

核心问题是Axios与Swagger UI对multipart/form-data中对象数组的序列化格式不一致：Axios会生成带索引的字段名（如propertyOptions[0].key=xxx），而Swagger UI默认采用无索引的重复字段名（如propertyOptions.key=xxx重复提交），导致后端无法正确解析。以下是几种可行解决方案：

方案1：配置Swagger强制生成索引式字段名 #

.NET（Swashbuckle） #

1. 自定义Schema映射明确数组结构，并添加操作过滤器强制生成带索引的表单字段：

services.AddSwaggerGen(c =>
{
    // 为PropertyOption数组指定Schema结构
    c.MapType<List<PropertyOption>>(() => new OpenApiSchema
    {
        Type = "array",
        Items = new OpenApiSchema
        {
            Type = "object",
            Properties = new Dictionary<string, OpenApiSchema>
            {
                { "key", new OpenApiSchema { Type = "string" } },
                { "value", new OpenApiSchema { Type = "string" } }
            }
        }
    });

    // 注册自定义操作过滤器
    c.OperationFilter<MultipartArrayOperationFilter>();
});

// 自定义操作过滤器实现
public class MultipartArrayOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var arrayParams = operation.Parameters
            .Where(p => p.Name.Equals("propertyOptions", StringComparison.OrdinalIgnoreCase))
            .ToList();

        foreach (var param in arrayParams)
        {
            param.Extensions.Add("x-ms-form-encoding", new OpenApiString($"{param.Name}[{{index}}].{{property}}"));
        }
    }
}

Java（Springdoc/Springfox） #

1. 通过自定义SchemaProcessor调整数组序列化规则：

@Component
public class MultipartArraySchemaProcessor implements SchemaProcessor {
    @Override
    public void process(SchemaProperty schemaProperty, SchemaProcessingContext context) {
        if ("propertyOptions".equals(schemaProperty.getPropertyName()) && schemaProperty.getSchema().isArray()) {
            // 指定数组使用索引式表单提交格式
            schemaProperty.getSchema().addExtension("x-form-array-format", "indexed");
        }
    }
}

也可直接在实体类字段上添加注解：

@Schema(
    name = "propertyOptions",
    extensions = {
        @Extension(
            properties = @ExtensionProperty(name = "x-form-array-format", value = "indexed")
        )
    }
)
private List<PropertyOption> propertyOptions;

方案2：修改后端兼容两种序列化格式 #

若Swagger配置成本较高，可调整后端参数解析逻辑，同时支持索引式和非索引式的数组提交：

• .NET：自定义IModelBinder，在绑定propertyOptions时同时解析两种格式的表单数据。
• Java：自定义HandlerMethodArgumentResolver，或使用@RequestParam配合手动拼接数组对象。

方案3：手动修改Swagger请求（临时测试用） #

仅用于临时调试时，可在Swagger UI的请求表单中手动修改字段名，模拟Axios的序列化格式：

• 将propertyOptions.key改为propertyOptions[0].key，propertyOptions.value改为propertyOptions[0].value
• 新增元素时依次使用propertyOptions[1].key、propertyOptions[1].value格式。

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