NestJS中Swagger泛型响应类型显示异常的解决方案咨询

问题核心：TypeScript泛型是编译时类型，运行时不存在具体的T值，所以@ApiResponseProperty({ type: T })无法生效，Swagger只能识别到默认的Item类型（可能是项目中第一个被关联的泛型参数）。

以下是具体解决方法：

1. 注册泛型参数模型 #

首先用@ApiExtraModels把所有需要作为泛型参数的DTO（如Item、Tag）注册到Swagger，让Swagger能识别这些模型：

import { ApiExtraModels } from '@nestjs/swagger';
import { Item } from './item.dto';
import { Tag } from './tag.dto';

// 注册所有需要作为泛型参数的DTO
@ApiExtraModels(Item, Tag)
export class RegisteredModels {}

2. 自定义分页响应装饰器（推荐） #

创建一个通用装饰器，自动生成对应泛型类型的Swagger响应定义，避免重复代码：

import { applyDecorators, ApiResponse, getSchemaPath } from '@nestjs/swagger';
import { PaginatedResult } from './paginated-result.dto';

export function ApiPaginatedResponse<T>(model: new () => T) {
  return applyDecorators(
    ApiResponse({
      status: 200,
      schema: {
        allOf: [
          // 引用基础的PaginatedResult模型
          { $ref: getSchemaPath(PaginatedResult) },
          // 覆盖data字段的类型为具体的泛型数组
          {
            properties: {
              data: {
                type: 'array',
                items: { $ref: getSchemaPath(model) },
              },
            },
          },
        ],
      },
    }),
  );
}

3. 在控制器中使用装饰器 #

在需要返回PaginatedResult<Tag>的接口上，使用自定义装饰器指定具体的泛型模型：

import { Controller, Get } from '@nestjs/common';
import { Tag } from './tag.dto';
import { ApiPaginatedResponse } from './api-paginated-response.decorator';
import { PaginatedResult } from './paginated-result.dto';

@Controller('tags')
export class TagsController {
  @Get()
  @ApiPaginatedResponse(Tag)
  getTags(): PaginatedResult<Tag> {
    // 业务逻辑实现
    return { data: [] };
  }
}

替代方案：手动指定接口响应Schema #

如果不想自定义装饰器，也可以在接口的@ApiResponse中直接写schema：

@Get()
@ApiResponse({
  status: 200,
  schema: {
    allOf: [
      { $ref: getSchemaPath(PaginatedResult) },
      {
        properties: {
          data: {
            type: 'array',
            items: { $ref: getSchemaPath(Tag) },
          },
        },
      },
    ],
  },
})
getTags(): PaginatedResult<Tag> {
  return { data: [] };
}

这样处理后，Swagger就能正确显示PaginatedResult<Tag>的响应结构，而不会默认显示Item类型了。

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