NestJs Swagger如何实现枚举与字符串混合类型的ApiProperty定义？

你可以放弃使用oneOf，转而通过字符串类型+枚举选项+允许未知值的组合实现需求，同时配合后端校验规则，就能同时支持枚举预设值和任意字符串输入。

正确代码示例 #

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

export enum VehicleTypes {
  CAR = 'Car',
  BUS = 'Bus',
  TRUCK = 'Truck'
}

export class YourDto {
  @ApiProperty({
    type: 'string',
    enum: VehicleTypes,
    allowUnknownEnumValues: true,
    description: '支持预设枚举值（Car/Bus/Truck），也接受任意自定义字符串'
  })
  @Expose()
  @IsString()
  @IsEnum(VehicleTypes, { allowUnknownValue: true })
  vehicleType: VehicleTypes | string;
}

关键配置说明 #

1. Swagger展示层面

   • type: 'string'：明确字段基础类型为字符串，这是枚举值和任意字符串的共同类型
   • enum: VehicleTypes：让Swagger UI显示枚举选项，方便调用方选择预设值
   • allowUnknownEnumValues: true：核心配置，告诉Swagger允许输入枚举之外的字符串，不会将非枚举值标记为格式错误

2. 后端校验层面

   • @IsString()：确保输入值是字符串格式，拦截非字符串类型的非法输入
   • @IsEnum(VehicleTypes, { allowUnknownValue: true })：允许枚举外的字符串通过校验，同时保留对枚举值的合法性校验（如果不需要枚举值校验，可直接去掉这个装饰器，只保留@IsString()）

为什么之前的oneOf方案不生效？ #

oneOf在OpenAPI规范中表示字段必须严格匹配其中一个定义的类型，但你实际需要的是字符串类型下包含枚举推荐值，而非互斥的两种类型。使用oneOf会让Swagger将枚举和字符串视为两个独立的类型分支，反而无法实现“既支持枚举又支持任意字符串”的效果。

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