NestJS - 2 Swagger로 API 문서 작성하기

이번에는 API문서를 보여주는 툴인 Swagger를 Nest에 적용시켜보고자한다. API문서가 사실 반드시 써야되고, 약간 닥쳐서 쓰려면 뭔가 귀찮기도해서 이런 툴이 있으면 쓰는게 나을 것 같긴하다..

NestJs는 기본적으로 fastify랑 express 둘 다 지원하긴 하는데, fastify로 Nest를 구성하는 문서나 커뮤니티가 express에 비해 너무 부족하다고 했다.. 그래서 나는 express로 Nest project를 구성했다.

프로젝트에 swagger 적용

Nest 공식 문서에 가면 swagger 세팅 법까지 전부 나와있는데, 그걸 우선 똑같이 쓴다.

npm i --save @nestjs/swagger swagger-ui-express

후에 프로젝트의 main.ts에 들어가 swagger를 사용하겠다고 선언을 해주면 된다. title, description, version은 추후에 확인할 수 있으니 보고 수정하면 된다.

main.ts

...
  const config = new DocumentBuilder()
    .setTitle('Nest Project title')
    .setDescription('Description for docs')
    .setVersion('1.0.0')
    .build();
  const document: OpenAPIObject = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('{endpoint}', app, document);
...

주의할 것은 마지막줄 SwaggerModule.setup에서 첫 번째 인자로 들어간 '{endpoint}'값이다. 이것이 url에서 endpoint로 적용되기 때문에, 이를 수정하면 API문서를 확인할 수 있는 url도 바뀐다.

이렇게만 해준 뒤 npm run start:dev 명령어를 통해 서버를 켠다.
후에 https://localhost:{port}/{endpoint}/로 들어가면

다음과 같은 화면을 만날 수 있다.

API 문서가 뜨긴 했는데 아직 뭔가 부족하다. 어떤 메소드가 어떤 역할을 맡는지도 모르고, 각 method 별로 어떤 파라미터를 보내야되는지도 아직 확인할 수 없다. 때문에 추가적으로 세팅을 해줘야된다.

Swagger 추가 세팅

1) method description

위 사진을 보면 각 method별로 endpoint와 HTTP method만 적혀있지, 그것들이 어떤 역할을 하는지는 나와있지 않다.
이는 코드를 짠 사람만 알 수 있고 다른 사람들이 이해하려면 코드를 또 읽어보기까지 해야된다.
프론트엔드 엔지니어와 협업중이라면 아마 더욱 불필요한 오버헤드일 것이다.

  @ApiOperation({ summary: 'signup' })
  @Post()
  async signUp(@Body() body: SignUpDto) {
    return await this.accountService.signUp(body);
  }

다음처럼 모든 method에 @ApiOperation({ summary: '설명' }) 데코레이터를 입히면 swagger 문서에서도 그 문서가 하는 역할을 바로 확인할 수 있다.

2) method parameter

DTO를 사용하는 method라면, 아래 코드에서처럼 @ApiProperty decorator를 설정해줌으로써 어떤 파라미터를 넘겨야되는지 swagger 문서에 보여줄 수 있다.

import { ApiProperty } from '@nestjs/swagger';
import { IsEmail, IsNotEmpty, IsString } from 'class-validator';

export class SignUpDto {
  @ApiProperty({
    example: '[email protected]',
    description: 'user email',
    required: true,
  })
  @IsEmail()
  @IsNotEmpty()
  email: string;

  @ApiProperty({
    example: 'examplename',
    description: 'user name',
    required: true,
  })
  @IsString()
  @IsNotEmpty()
  username: string;

  @ApiProperty({
    example: 'examplePw',
    description: 'user password',
    required: true,
  })
  @IsString()
  @IsNotEmpty()
  password: string;
}

다음처럼 SignUpDto에 Swagger decorator를 적용한다면 swagger 문서에서 signup method에 어떤 값을 넘겨줘야 하는지 간략하게 보여줄 수 있다.

3) method response

또 해당 method로 request를 보냈을 때 어떤 response들을 받을 수 있는지 테스트 하기 위해서 @ApiResponse decorator를 사용할 수 있다.

  @ApiResponse({
    status: 403,
    description: 'Not Login error',
  })
  @ApiResponse({
    status: 200,
    description: 'Success for signUp',
    type: ReadOnlyAccountDto,
  })
  @ApiOperation({ summary: 'signup' })
  @Post()
  async signUp(@Body() body: SignUpDto) {
    return await this.accountService.signUp(body);
  }

ReadOnlyAccountDto는 Response를 위해 추가적으로 만들어준 dto로 response시 들어가도 되는 내용들을 담았다.
Swagger에서의 결과

이제 response까지 넣어줬으니, swagger에서 API test도 진행할 수 있으나 굳이? 싶어서 이는 추가하지 않았다.

맺으며..

자동으로 API문서를 readility높게 작성해준다는 점에서 앞으로 많은 프로젝트에 Swagger를 적용시켜볼 생각이다.
추가적으로 Dto를 상속을 하는 식으로 코드를 수정하는 것이 좋겠다..

참고

GitHub repo: https://github.com/cyw320712/NESTJS-A-TO-Z