NestJS Swagger插件使用管道运算符时无法识别DTO求助

方法一：用 @ApiProperty 显式声明联合类型 #

Swagger CLI 插件默认无法自动解析 TypeScript 联合类型，需手动通过 oneOf 字段指定对应 DTO 的 Schema，同时借助 getSchemaPath 生成正确的引用路径：

import { ApiProperty, getSchemaPath } from '@nestjs/swagger';
import { GetAbcResponseDto, GetXycResponseDto } from './your-dto-path';

class YourWrapperDto {
  @ApiProperty({
    oneOf: [
      { $ref: getSchemaPath(GetAbcResponseDto) },
      { $ref: getSchemaPath(GetXycResponseDto) },
    ],
    nullable: true,
  })
  data?: GetAbcResponseDto | GetXycResponseDto;
}

方法二：检查并优化 Swagger 插件配置 #

确保 nest-cli.json 中的 Swagger 插件开启了类型兼容相关选项，帮助插件更好地识别复杂类型：

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@nestjs/swagger",
        "options": {
          "classValidatorShim": true,
          "introspectComments": true,
          "dtoFileNameSuffix": [".dto.ts"] // 确保匹配你的DTO文件名后缀
        }
      }
    ]
  }
}

方法三：用 @ApiExtraModels 注册未被自动识别的 DTO #

如果联合类型中的 DTO 没有直接作为控制器返回值被引用，Swagger 不会自动注册其 Schema，需在控制器或模块上显式注册：

import { ApiExtraModels, ApiOkResponse, getSchemaPath } from '@nestjs/swagger';
import { GetAbcResponseDto, GetXycResponseDto } from './your-dto-path';

@ApiExtraModels(GetAbcResponseDto, GetXycResponseDto)
@Controller('demo')
export class DemoController {
  @ApiOkResponse({
    schema: {
      oneOf: [
        { $ref: getSchemaPath(GetAbcResponseDto) },
        { $ref: getSchemaPath(GetXycResponseDto) },
      ],
    },
  })
  async getDemoData(): Promise<GetAbcResponseDto | GetXycResponseDto> {
    // 业务逻辑实现
  }
}

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