Swagger OpenAPI3 发送form-data对象数组服务端收到字符串问题

问题现象 #

发送携带对象数组的multipart/form-data请求时，Express服务端接收到的数组内所有对象均被转换为JSON字符串，无法修改服务端代码，仅可通过调整Swagger配置解决。

• 服务端预期接收格式：{ video: [{ _id: "string" }] }
• 实际接收格式：{ video: [ '{"_id": "string"}' ] }
• 当前使用的Swagger配置：

"requestBody": {
     "content": {
         "multipart/form-data": {
            "schema": {
               "type": "object",
               "properties": {
                   "video[]": {
                    "type": "array",
                    "items": {
                       "type": "object",
                       "properties": {
                          "_id": {
                             "type": "string"
                          }
                       }
                    },
                    "describtion": "Video ids "
                 }
               }
            },
            "encoding": {
               "video[]": {
                 "contentType": "application/json",
                 "explode": true
               }
            }
         }
     }
 }

问题根因 #

配置存在两处错误：

• 字段名手动添加了[]后缀，和Swagger原生数组序列化规则冲突
• encoding节点开启了explode: true，该配置会将数组的每个元素拆分为独立的同名表单项，每个元素单独序列化为JSON字符串，最终后端拿到的就是字符串组成的数组，而非对象数组。

修复后配置 #

按以下规则调整即可：

• 将字段名从video[]改为video，无需手动添加数组后缀
• 删除encoding节点下的explode: true配置
• 保留contentType: application/json配置，确保数组整体按JSON格式序列化
• 顺便修正原配置中的拼写错误：将describtion改为标准字段description，避免Swagger UI解析异常

调整后的完整配置：

"requestBody": {
     "content": {
         "multipart/form-data": {
            "schema": {
               "type": "object",
               "properties": {
                   "video": {
                    "type": "array",
                    "items": {
                       "type": "object",
                       "properties": {
                          "_id": {
                             "type": "string"
                          }
                       }
                    },
                    "description": "Video ids"
                 }
               }
            },
            "encoding": {
               "video": {
                 "contentType": "application/json"
               }
            }
         }
     }
 }

调整后Swagger会将整个video数组序列化为单个JSON格式的表单项，Express侧的form-data解析中间件会自动识别JSON格式的字段值，反序列化为原生JS对象数组，和服务端预期格式完全匹配。

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