Swagger 2.0下form-data对象数组建模及请求校验错误问题问询

报错原因 #

当前syllabi、lessons数组校验失败，是因为Swagger 2.0对form-data类型的数组参数默认使用csv序列化格式，会将数组元素拼接为逗号分隔的单个字符串传递，后端无法识别为数组类型，因此触发校验错误。

正确配置规则 #

• 简单类型数组（元素为string、integer等基础类型）需要显式指定collectionFormat: multi，该配置会将每个数组元素作为独立的同名form参数传递，符合后端数组解析规则
• 对象类型数组（如skills每个元素包含name、id等属性）Swagger 2.0原生不支持结构化定义，可根据数组长度是否固定选择对应方案：
  • 固定长度数组：可按索引逐个定义参数，参数名遵循skills[N][属性名]格式，N从0开始递增
  • 可变长度数组：无需逐个定义参数，在接口描述中说明参数命名规则，生成代码后手动拼接参数即可

完整配置示例 #

parameters:
  - $ref: '#/parameters/xAccessTokenHeader'
  - in: formData
    name: name
    type: string
    required: true
  - in: formData
    name: status
    type: integer
  - in: formData
    name: level
    type: integer
    required: true
  - in: formData
    name: classification
    type: integer
    required: true
  - in: formData
    name: description
    type: string
    required: true
  - in: formData
    name: icon
    type: string
    required: true
  # 简单类型数组添加collectionFormat: multi
  - in: formData
    name: syllabi
    type: array
    items:
      type: integer
    collectionFormat: multi
  - in: formData
    name: institutions
    type: array
    items:
      type: integer
    collectionFormat: multi
  # 固定长度的skills对象数组按索引定义
  - in: formData
    name: skills[0][name]
    type: string
  - in: formData
    name: skills[0][id]
    type: string
  - in: formData
    name: skills[0][selected]
    type: boolean
  - in: formData
    name: skills[0][type]
    type: string
  - in: formData
    name: skills[1][name]
    type: string
  - in: formData
    name: skills[1][id]
    type: string
  - in: formData
    name: skills[1][selected]
    type: boolean
  - in: formData
    name: skills[1][type]
    type: string
  - in: formData
    name: lessons
    type: array
    items: 
      type: string
    collectionFormat: multi
  - in: formData
    name: status_mode
    type: integer
responses:
  "201":
    description: "Created"

Java调用适配 #

按上述配置重新生成Swagger Java代码后，原有调用逻辑无需修改即可正常发送符合要求的请求。如果自动生成的代码仍存在序列化问题，可手动调整API实现逻辑：

• 简单数组遍历元素，逐个添加为同名form参数
• skills列表遍历每个元素和属性，按skills[索引][属性名]的格式组装参数名添加到form请求中

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