NestJS中Swagger规范是否支持泛型类型？

问题根源在于TypeScript泛型是编译时特性，运行时会被类型擦除，所以Swagger无法识别GenericEventDto中data和attributes字段的具体泛型类型，导致文档里显示为空对象。以下是几种兼顾复用性和Swagger兼容性的解决方案：

方案1：创建具体子类（最简单直接） #

通过继承泛型DTO生成具体类型，Swagger能正常识别子类的结构：

首先定义具体DTO子类：

// 为每个泛型组合创建子类，复用GenericEventDto的字段逻辑
export class ConcreteEventDto extends GenericEventDto<ConcreteData, ConcreteAttributes> {}

然后在控制器中使用这个子类：

export class Controller {
  @ApiBody({ type: ConcreteEventDto })
  async handleIncomingMessage(
    @Body() event: ConcreteEventDto
  ): Promise<void> {
    // 执行操作
  }
}

这种方式虽然需要为不同的泛型组合创建子类，但完全复用了GenericEventDto的核心逻辑，避免重复编写字段和装饰器。

方案2：利用Swagger Schema组合（无需创建子类） #

通过@ApiExtraModels注册泛型参数类型，再通过allOf组合生成完整的Swagger Schema：

1. 先调整GenericEventDto的@ApiProperty配置（因为运行时泛型不存在，先指定基础类型）：

export class GenericEventDto<D, A> {
  @ApiProperty({ type: 'object' })
  @Expose()
  data: D

  @ApiProperty({ type: 'object' })
  @Expose()
  attributes: A

  @ApiProperty()
  @Expose()
  messageId: string
}

2. 在控制器中注册额外模型并组合Schema：

import { ApiExtraModels, ApiBody, getSchemaPath } from '@nestjs/swagger';

@ApiExtraModels(ConcreteData, ConcreteAttributes)
export class Controller {
  @ApiBody({
    schema: {
      allOf: [
        { $ref: getSchemaPath(GenericEventDto) },
        {
          properties: {
            data: { $ref: getSchemaPath(ConcreteData) },
            attributes: { $ref: getSchemaPath(ConcreteAttributes) }
          }
        }
      ]
    }
  })
  async handleIncomingMessage(
    @Body() event: GenericEventDto<ConcreteData, ConcreteAttributes>
  ): Promise<void> {
    // 执行操作
  }
}

方案3：自定义装饰器（复用性最优） #

封装一个通用装饰器，简化不同泛型组合的Swagger配置：

1. 创建自定义装饰器：

import { applyDecorators, ApiBody, ApiExtraModels, getSchemaPath, Type } from '@nestjs/swagger';

export function ApiGenericEventBody<TData, TAttributes>(dataType: Type<TData>, attributesType: Type<TAttributes>) {
  return applyDecorators(
    ApiExtraModels(dataType, attributesType, GenericEventDto),
    ApiBody({
      schema: {
        allOf: [
          { $ref: getSchemaPath(GenericEventDto) },
          {
            properties: {
              data: { $ref: getSchemaPath(dataType) },
              attributes: { $ref: getSchemaPath(attributesType) }
            }
          }
        ]
      }
    })
  );
}

2. 在控制器中直接使用装饰器：

export class Controller {
  @ApiGenericEventBody(ConcreteData, ConcreteAttributes)
  async handleIncomingMessage(
    @Body() event: GenericEventDto<ConcreteData, ConcreteAttributes>
  ): Promise<void> {
    // 执行操作
  }
}

后续复用GenericEventDto时，只需调用@ApiGenericEventBody并传入对应的具体类型即可，无需重复编写Swagger Schema配置。

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