OpenAPI 3.0.3中multipart/form-data数组参数格式异常求助

算力阿峰

2026-7-2

解决multipart/form-data数组元素被合并的问题

你遇到的问题是multipart/form-data请求里的数组被解析成了单个逗号分隔的字符串，核心原因是OpenAPI默认的数组序列化方式和服务端期望的不匹配。按以下步骤修改即可：

1. 调整OpenAPI的字段定义

把字段名从'genreIds[]'和'languageIds[]'改成genreIds和languageIds，方括号后缀没必要，反而会干扰解析。
给数组字段添加style: form和explode: true参数，明确告诉OpenAPI要生成重复的字段名（而非逗号分隔），这样服务端就能识别每个元素。
简化genreIds的items定义，oneOf在这里是多余的，直接指定类型为string即可。

修正后的请求体代码：

requestBody: {
  content: {
    'multipart/form-data': {
      schema: {
        type: 'object',
        properties: {
          email: { type: 'string' },
          password: { type: 'string' },
          confirmPassword: { type: 'string' },
          fullName: { type: 'string' },
          avatar: { type: 'string', format: 'binary' },
          genreIds: {
            type: 'array',
            items: { type: 'string' },
            style: 'form',
            explode: true
          },
          languageIds: {
            type: 'array',
            items: { type: 'string', default: '' },
            style: 'form',
            explode: true
          },
        },
      },
    },
  },
}