Nest.js API 문서화 — Swagger Module

현재 진행 중인 토이프로젝트는 프론트엔드 개발자분과 함께 협업으로 진행하고 있는 프로젝트이다.

그렇기에 백엔드를 실제로 외부에서 사용이 가능한 상태로 만들어야 하고, 올바르게 사용할 수 있도록 참고할 수 있는 매뉴얼도 필요하다.

Nest.js에는 프론트엔드와 협업을 위한 다양한 설정을 내부에서 혹은 라이브러리 호환을 제공한다. 그 중 가장 기본이 되는 설정별로 문서를 구분해 하나씩 정리해보자.

Swagger UI

Swagger 설정을 하는 이유

백엔드와 프론트엔드 간 협업 시, API 개발 문서화 도구 혹은 테스트 툴은 필수적이다. 물론 백엔드 개발만 하더라도 API 기능을 테스트하는 용도로 자주 사용하지만, 프론트엔드 개발자에게 백엔드에서 개발한 메소드에 대해 설명하고 테스트할 수 있도록 일종을 가이드를 제공하는 역할을 한다.

Postman, Insomnia, Swagger UI 등 다양한 플랫폼과 기술이 있는데, 서비스별로 제공 기능과 사용 방법이 달라 용도와 팀의 스타일에 맞는 방식으로 선택해야 한다. 그 중 Swagger UI는 현재 프론트엔드 파트너와 함께 현업에서 사용하고 있는 방식이기에 익숙하기도 하고, 한번 배워본거 좀더 깊숙히 공부해보고자 선택했다.

소스코드에 직접 문서화 코드를 작성하기에 번거롭거나 코드가 다소 지저분해질 수 있지만, 그 자체로 메소드 설명의 주석처럼 활용될 수 있다. 웹 브라우저를 띄우는 방식이기 때문에 직접 웹 기능으로 테스트 해볼 수 있고, 배포된 후에는 외부에 공개하기도 쉽다. ~~개인적으로 문서화는 디자인이 이쁘다는 느낌을 받긴 어렵다.~~

Swagger 설정

스웨거를 사용하기 위해선 라이브러리를 설치해야 합니다. Nest.js 전용 스웨거 라이브러리를 설치해줍니다.

npm install @nestjs/swagger

(swagger-ui-themes를 이용하면 스웨거 문서를 꾸밀 수 있다고 하는데 나중에 한번 알아봐야겠다.)

스웨거의 설정은 SwaggerModule이 담당한다. 이 모듈은 기본적으로 main.ts에 설정해둔다.

import { AppModule } from './app/app.module';
import { NestFactory } from '@nestjs/core';
import { ConfigService } from '@nestjs/config';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const config = app.get(ConfigService);

  const port = config.get<number>('PORT');

  const swaggerConfig = new DocumentBuilder()
    .setTitle('Daily Record')
    .setDescription('Project "Daily Record" API')
    .setVersion('1.0')
    .addBearerAuth()
    .build();
  const document = SwaggerModule.createDocument(app, swaggerConfig);
  SwaggerModule.setup('api', app, document);

  await app.listen(port);
}
bootstrap();

먼저 DocumentBuilder 클래스의 인스턴스를 생성해 스웨거 문서를 생성하기 위한 설정을 준비를 해둔다. 문서의 제목와 내용, 버전 등을 등록할 수 있으며, 특히 addBearerAuth()를 이용해 Bearer 토큰 기반의 인증을 할 수 있도록 설정해줄 수 있다.(토큰 인증방식으로 기능을 구현한다면 필수라고 할 수 있다.)

준비해둔 설정을 SwaggerModule 클래스의 DocumentBuilder() 메소드를 이용해 스웨서 문서를 생성한 후, setup() 메소드를 이용해 생성한 문서를 노출시킨다. 이때, 첫번째 인자로 전달된 값(’api’)이 API 주소의 첫번째 엔드포인트로 사용된다.

Swagger

Swagger 활용: 데코레이터

스웨거 문서를 만들기 위한 재료는 주로 데코레이터로 사용한다. 메소드의 제목이나 내용, 미디어타입 설정 등 문서를 꾸밀 수 있는 다양한 옵션을 활용해 API 기능을 명확히 정의할 수 있다.

스웨서 데코레이터는 옵션을 Controller와 DTO에서 사용된다. 사용 예시를 간략하게 살펴보자.

Controller

import { Body, Controller, Post } from '@nestjs/common';
import { ApiBearerAuth, ApiBody, ApiConsumes, ApiOperation, ApiTags } from '@nestjs/swagger';
import { UserService } from './user.service';
import { CreateUserDto } from '../../shared/dto/user.dto';

@Controller('users')
@ApiTags('User')
@ApiBearerAuth()
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post('sign-up')
  @ApiOperation({ summary: '회원가입', description: 'email은 중복 불가입니다.' })
  async signUp(@Body() userData: CreateUserDto) {
    return await this.userService.signUp(userData);
  }
}

DTO

import { ApiProperty } from '@nestjs/swagger';
import { IsEmail, IsString } from 'class-validator';
import { AuthType } from 'src/shared/types/enums/user.enum';

export class CreateUserDto {
  @IsEmail()
  @ApiProperty({ format: 'email' })
  readonly email: string;

  @IsString()
  @ApiProperty({ example: '테스트' })
  readonly nickname: string;

  @IsString()
  @ApiProperty({ example: 'qwer1234' })
  password: string;

  @IsString()
  @ApiProperty({ example: AuthType.BASIC })
  authType: AuthType = AuthType.BASIC;
}

위 두 파트의 설정을 하면 아래와 같은 기본적인 문서 화면을 볼 수 있다.

Swagger

Swagger UI

Swagger 설정을 하는 이유

Swagger 설정

Swagger 활용: 데코레이터

참고 자료