Nest.js Swagger 용 Decorator 작성

Swagger

Swagger 는 서버의 자원을 사용하기 위해 제공 되는 API를 문서화를 하도록 해주는 라이브러리 입니다. 해당 라이브러리를 잘 정리를 해둔 상태라면 다른 서버 또는 개발에 유용하게 사용 될 수 있습니다. 그리고 자동적으로 데이터 변경을 감지하고 문서를 변경해줌으로서 이전에 Express.js 보다 좀 더 편리하게 문서를 작성할 수 있습니다. 해당 글에서는 기본적인 Swagger 사용법은 언급하지 않고 있으니 Nest.js 의 Swagger 기본 설치 및 문법을 보시려면 다른 글을 참고해주세요.

 

Decorator 작성

Decorator 는 자바의 Annotation 과 같은 기능을 제공하고 있습니다. 커스텀 데코레이터를 생성을 하고 해당 데코레이터를 반복적으로 사용하는 환경을 만들어 줍니다. 해당 내용에 대해서 궁금하신분은 AOP 에 관한 내용을 좀 더 보시면 좋을 듯 합니다.

 

AOP(Aspect Oriented Programming)

 

Decorator 사용 이전의 코드

Swagger API 를 사용하면 Controller 에 대한 반환값을 미리 보여주는 문서를 작성해야 합니다. 그런경우 Swagger 에서 제공하는 기본 코드를 사용하면 아래와 같습니다.

@ApiCreatedResponse({
  schema: {
    allOf: [{ $ref: getSchemaPath(FindVideoResDto) }],
  },
}),

이미 구조화된 Dto 를 Response 스키마로 제공 해줌으로써 그에 맞는 반환 값이 자동적으로 Swagger 에 문서화가 됩니다.

ResDto 값이 자동으로 사진과 같이 입력됨

Controller에서 Swagger Api Decorator를 사용해도 Swagger에 나오지 않는 경우
Controller에 사용되는 Swagger의 경우 Request Body로 지정되지 않으면 자동으로 Swagger 문서화가 되지 않고 있습다. 그러므로 @Controller 상단에 @ApiExtraModels를 추가 해줌으로써 수동으로 입력해야 됩니다.

@ApiTags('Auth')
@ApiExtraModels(SignupResDto, SigninResDto)
@Controller('api/auth')
export class AuthController {
  ...
}​

 

Decorator 적용 이후의 코드

/src/common/decorator/swagger.decorator.ts 경로에 파일을 생성하고 Decorator를 작성해줍니다. 

export const ApiGetResponse = <TModel extends Type<any>>(model: TModel) => {
  return applyDecorators(
    ApiOkResponse({
      schema: {
        allOf: [{ $ref: getSchemaPath(model) }],
      },
    }),
  );
};

 

코드	설명
TModel extends Type<any>	any 타입을 상속받은 TModel을 의미합니다.  즉, 지네릭스를 통해 타입 제한을 받고 있어야 사용가능한 데코레이션을 의미합니다.

 

이렇게 데코레이터를 작성하고 다시 Controller에 사용해주도록 하겠습니다. 

 

  @ApiGetItemsResponse(FindUserResDto)
  @Get()
  findAll(@Query() { page, size }: PageReqDto) {
    return this.userService.findAll();
  }

 

데코레이터에 파라미터만 넘겨 줌으로써 자동으로 타입을 읽고 그에 맞는 Swagger 문서를 작성하는 코드를 사용하게 되었습니다. 

 

AOP 라는 기술을 잘 사용하여 공동 관심사를 이렇게 다른 데코레이터로 제공해주는 것이 중요한 포인트입니다.