NestJS Swagger单参数无法转为字符串数组问题求助

针对Swagger UI传递单个数组参数时控制器收到字符串而非数组的问题，提供三种可行方案：

方案1：配置Swagger ApiQuery参数格式 #

在控制器方法上通过@ApiQuery指定参数的style和explode属性，让Swagger UI以多参数形式渲染数组输入，确保后台解析为数组：

import { Controller, Get, Query } from '@nestjs/common';
import { ApiQuery, ApiTags } from '@nestjs/swagger';
import { List } from './dto/list.dto';

@ApiTags('list')
@Controller('list')
export class ListController {
  @Get()
  @ApiQuery({
    name: 'categories',
    type: String,
    isArray: true,
    required: false,
    style: 'form',
    explode: true, // 启用后Swagger UI会生成多个同名字段输入框
  })
  getList(@Query() query: List) {
    return query;
  }
}

方案2：自定义参数转换管道 #

创建管道统一处理单个字符串转数组的逻辑，可全局或局部使用：

// parse-array.pipe.ts
import { PipeTransform, Injectable, ArgumentMetadata } from '@nestjs/common';

@Injectable()
export class ParseArrayPipe implements PipeTransform {
  transform(value: any, metadata: ArgumentMetadata) {
    // 仅处理query参数中的单个字符串
    if (metadata.type === 'query' && typeof value === 'string') {
      return [value];
    }
    return value;
  }
}

控制器中使用：

@Get()
getList(@Query(new ParseArrayPipe()) query: List) {
  return query;
}

方案3：在DTO中通过class-transformer处理 #

利用class-transformer的@Transform装饰器，在DTO层自动转换单个字符串为数组：

import { ApiProperty } from '@nestjs/swagger';
import { IsOptional } from 'class-validator';
import { Transform } from 'class-transformer';

export class List {
  @ApiProperty({ isArray: true, type: String, required: false })
  @IsOptional()
  @Transform(({ value }) => typeof value === 'string' ? [value] : value)
  public categories?: string[];
}

以上三种方案均可实现：传递单个参数时控制器接收['25']数组，传递多个参数时接收['25','21']数组。

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