Swagger生成multipart/form-data数组格式问题（NestJS）

当你的CreatePersonDto包含字符串数组字段clothes时，Swagger默认生成的curl请求会用逗号分隔的字符串传递数组，导致NestJS无法正确解析。可以通过配置Swagger的参数样式来让它生成clothes=shirt&clothes=pants或clothes[0]=shirt&clothes[1]=pants的格式，具体方法如下：

方法1：在DTO字段上配置Swagger属性 #

直接在DTO的数组字段上通过@ApiProperty指定style和explode参数，强制Swagger生成拆分的数组参数：

import { IsArray, IsString } from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';

export class CreatePersonDto {
  @IsArray()
  @IsString({ each: true })
  @ApiProperty({
    type: [String],
    style: 'form',
    explode: true,
    description: '服装列表，支持多参数传递'
  })
  clothes: string[];
}

方法2：在控制器方法上配置查询参数 #

如果clothes是查询参数（通过@Query()接收），可以在控制器方法上用@ApiQuery单独配置该参数的格式：

import { Controller, Get, Query } from '@nestjs/common';
import { ApiQuery, ApiTags } from '@nestjs/swagger';
import { CreatePersonDto } from './dto/create-person.dto';

@ApiTags('person')
@Controller('person')
export class PersonController {
  @Get()
  @ApiQuery({
    name: 'clothes',
    type: [String],
    style: 'form',
    explode: true,
    required: false
  })
  getPerson(@Query() dto: CreatePersonDto) {
    return dto;
  }
}

关键配置说明 #

• style: 'form'：指定参数采用表单格式的序列化方式
• explode: true：开启数组拆分，让Swagger将数组元素拆分为多个独立的参数（同名字段或带索引的字段，取决于Swagger版本），而不是用逗号拼接成单个字符串

配置完成后，Swagger UI生成的curl请求就会自动使用拆分后的参数格式，NestJS也能正确将其解析为字符串数组。

注意：如果你的接口是接收JSON格式的请求体（application/json），默认就不会出现这个问题，JSON数组会被NestJS正常解析。此方案主要针对表单（application/x-www-form-urlencoded）或查询参数的场景。

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