如何在Swagger UI中通过multipart/form-data传递JSON数组？

问题原因 #

multipart/form-data 类型请求在OpenAPI 3.x中默认的序列化规则不会对嵌套对象数组自动包裹JSON结构，Swagger UI默认的explode策略会把数组元素直接拼接，导致丢失外层方括号。

解决方法 #

方案1：添加序列化规则配置（推荐）

在你的OpenAPI配置中补充encoding字段指定address参数的序列化方式，同时在字段属性中添加序列化规则，修改后的完整配置如下：

post:
  summary: Creates a user
  requestBody:
    content:
      multipart/form-data:
        schema:
          type: object
          properties: # Request parts
            id:
              type: string
              format: uuid
            address:
              type: array
              items:
                type: object
                properties:
                  street:
                    type: string
                  city:
                    type: string
              # 新增序列化规则
              style: form
              explode: false
            profileImage:
              type: string
              format: base64
        # 新增encoding配置指定参数编码格式
        encoding:
          address:
            contentType: application/json

添加后Swagger UI会自动将address数组序列化为[{"street":"xxx","city":"xxx"},...]的标准JSON数组格式传递。

方案2：兼容低版本Swagger UI

如果你使用的Swagger UI版本低于3.38.0不支持上述配置，可以直接将address字段的类型定义为string，使用时手动将数组序列化为JSON字符串传入，后端接收到参数后自行做JSON反序列化即可。

补充注意 #

如果后端使用SpringBoot、Node.js Express等框架，需要确认对应的参数解析器支持从multipart请求中解析JSON格式的数组参数，避免前端传参正确但后端接收失败的问题。

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