如何让NestJS Swagger包含仅通过$ref引用的DTO Schema？

方法一：用@ApiExtraModels强制注册DTO #

这是NestJS Swagger官方提供的方案，专门处理这类未被自动扫描到的Schema类：

1. 导入所需装饰器：

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

2. 在PriceSuggestionDto类上方添加@ApiExtraModels(PriceDto)，将PriceDto强制纳入Swagger的Schema注册表：

@ApiExtraModels(PriceDto)
export class PriceSuggestionDto {
  @ApiProperty({
    type: 'object',
    additionalProperties: { 
      $ref: getSchemaPath(PriceDto) 
    },
  })
  conditionPrices: Record<string, PriceDto>;
}

3. 确保控制器的响应注解正确指定返回类型，比如：

@Get('price-suggestions')
@ApiResponse({ status: 200, type: PriceSuggestionDto })
async getPriceSuggestions() {
  // 业务逻辑实现
}

修改后，Swagger会自动生成PriceDto的Schema，$ref能正常解析，conditionPrices的类型会显示为Record<string, PriceDto>，之前的错误提示也会消失。

方法二：间接引用触发自动扫描 #

如果不想使用@ApiExtraModels，可以在PriceSuggestionDto中添加一个不参与业务的临时属性，用来触发Swagger对PriceDto的扫描：

export class PriceSuggestionDto {
  @ApiProperty({
    type: 'object',
    additionalProperties: { 
      $ref: getSchemaPath(PriceDto) 
    },
  })
  conditionPrices: Record<string, PriceDto>;

  // 仅用于触发Swagger扫描，实际业务中不使用
  @ApiProperty({ type: PriceDto, required: false })
  private _dummy?: PriceDto;
}

不过这种方法不够优雅，更推荐使用官方提供的@ApiExtraModels方案。

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