[NestJS, TypeScript] Swagger API에 Generic Type 정의하는 방법

📒 [NestJS, TypeScript] Swagger에 Generic Type 정의하는 방법

---

백엔드에서 요청과 응답을 처리할 때 일정한 템플릿이 정해져 있는 경우가 있습니다.

export class SuccessResponse<T> {
  @ApiProperty({ description: '응답 데이터' })
  payload: T;
  
  @ApiProperty({ description: '상태코드' })
  code: string;
  
  @ApiProperty({ description: '호출된 URI' })
  request: string;
}

 
위 타입은 클라이언트의 요청을 성공적으로 처리하면 보내는 데이터 타입입니다.
이러한 중복되는 타입을 각 DTO마다 사용하면 불편함이 한두 가지가 아니어서 아래와 같이 제네릭 타입을 사용합니다.
 

@Get()
@ApiExtraModels(GetBrandListReq)
@ApiOkResponse({
  description: '브랜드 리스트',
  type: SuccessResponse<Brand[]>,
})
findByFilter(@Query() query: GetBrandListReq) {
  return this.brandService.findByFilter(query);
}

 

그런데 웬걸? 스웨이거에 타입이 표시가 안됩니다.
이유는 Swagger가 NestJS의 런타임 메타데이터를 기반으로 문서를 생성하는 데, TypeScript의 제네릭은 컴파일 단계에서 소멸되기 때문입니다.
 

이렇게 되면 확인하기도 불편하거니와, 프론트에서 swagger-typescript-api를 사용해 타입을 긁어올 때도 제대로 표시가 안되는 문제가 발생합니다.

 

📌 Swagger Generic Type 표시하기

이러한 현상을 해결하기 위해 getSchemaPath를 사용하는 방법도 있겠지만, 스웨이거 문서화 코드가 너무 길어지는 것이 맘에 안 들었습니다.

그래서 저는 다음과 같은 방법을 사용해 봤습니다.

import { mixin } from '@nestjs/common';

type Constructor<T = object> = new (...args: any[]) => T;

export class TypeUtil {
  static getSuccessResponse<T extends Constructor>(Base: T) {
    class Class extends SuccessResponse<T> {
      @ApiProperty({ type: Base, description: '응답 데이터' })
      payload: T;
    }
    return class SuccessResponse extends mixin(Class) {};
  }
  static getSuccessResponseList<T extends Constructor>(Base: T) {
    class Class extends SuccessResponseList<T> {
      @ApiProperty({ type: [Base], description: '응답 데이터' })
      payload: T;
    }
    return class SuccessResponseList extends mixin(Class) {};
  }
}

// dto
export class GetBrandListRes extends TypeUtil.getSuccessResponseList(Brand) {}

@Get()
@ApiExtraModels(GetBrandListReq)
@ApiOkResponse({
  description: '브랜드 리스트',
  type: GetBrandListRes,
})
findByFilter(@Query() query: GetBrandListReq) {
  return this.brandService.findByFilter(query);
}

 

🔎 Mixin을 이용해 새로운 클래스 반환

mixin은 클래스의 상속이나 확장의 개념이 아닌 두 개 이상의 클래스를 섞어 새로운 하나의 클래스를 반환하는 개념입니다.

import { mixin } from '@nestjs/common';

type Constructor<T = object> = new (...args: any[]) => T;

function mixinClass<T extends Constructor>(Base: T) {
  class Class extends Response<T> {
    property: T;
  }
  return class NewResponse extends mixin(Class) {};
}

위 코드는 TypeScript에서 기존 클래스를 확장하거나 동적으로 새로운 클래스를 생성하는 믹스인 패턴을 구현한 것입니다.
덕분에 컴파일 시점에 조합되는 제네릭을 우회해 런타임에 동적으로 클래스가 합쳐지게 되어 스웨이거에 타입을 표시할 수 있게 됩니다.