如何让NestJS Swagger插件支持Adyen等第三方库模型？

为啥继承第三方类不生效？ #

NestJS Swagger 依赖 class-validator、class-transformer 以及自身的 @ApiProperty 这类装饰器来解析类结构生成文档。第三方库（比如 @adyen/api-library）里的 Notification、NotificationResponse 这类类大多是纯 TypeScript 定义，不会附带这些装饰器元数据——哪怕你继承它们，Swagger 也抓不到属性信息，自然没法生成正确的文档。

可行的解决办法 #

1. 用 @ApiExtraModels 关联第三方类 #

不用复制所有属性，你可以做一个轻量的 DTO 类，通过 Swagger 装饰器直接关联第三方类：

import { ApiExtraModels, ApiProperty, getSchemaPath } from '@nestjs/swagger';
import { Notification } from '@adyen/api-library';

@ApiExtraModels(Notification)
export class AdyenNotificationDto {
  @ApiProperty({
    $ref: getSchemaPath(Notification),
  })
  data: Notification;
}

然后在控制器里用这个 DTO 作为请求体：

@Post('/adyen-webhook')
@ApiBody({ type: AdyenNotificationDto })
handleWebhook(@Body() body: AdyenNotificationDto) {
  // 业务逻辑
}

这种方式不用手动维护属性，但缺点是 Swagger 里的属性描述会比较简略，毕竟第三方类没加装饰器注释。

2. 动态给第三方类加装饰器 #

你可以在项目启动时，用脚本给第三方类的属性批量添加 @ApiProperty 装饰器，让 Swagger 能识别它们：

// 在 main.ts 最顶部执行这段代码
import { ApiProperty } from '@nestjs/swagger';
import { Notification, NotificationResponse } from '@adyen/api-library';

// 给 Notification 类的所有属性加 ApiProperty
Object.getOwnPropertyNames(Notification.prototype).forEach(prop => {
  ApiProperty()(Notification.prototype, prop);
});

// 同理处理 NotificationResponse
Object.getOwnPropertyNames(NotificationResponse.prototype).forEach(prop => {
  ApiProperty()(NotificationResponse.prototype, prop);
});

这样之后，你直接在控制器里用 Notification 作为 DTO 就行，Swagger 会自动解析属性。需要注意的是，如果第三方库更新了类结构，你可能要调整这段脚本的逻辑。

3. 手动定义 DTO（最稳妥但费点事） #

如果上面两种方法都满足不了你的需求（比如需要自定义属性描述、添加校验规则），那就只能手动把第三方类的属性复制到自定义 DTO 里，加上 Swagger 装饰器：

import { ApiProperty } from '@nestjs/swagger';

export class AdyenNotificationDto {
  @ApiProperty({ description: 'Adyen 通知事件编码' })
  eventCode: string;

  @ApiProperty({ description: '通知生成时间' })
  eventDate: string;

  // 其他属性按第三方类结构逐一复制并添加装饰器
}

这种方式能完全控制 API 文档的细节，但需要在第三方库更新时手动同步属性，适合对文档质量要求高的场景。

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