NestJS 기초 (11) API 문서 작성하기 (스웨거)

API 문서는 보통 개발한 API 기능을 명시하고 다른 개발자와 공유하기 위해 사용합니다. Nest에서는 스웨거(swagger)를 사용하여 간편하게 API 문서를 작성하고 이를 테스트해볼 수 있습니다.

스웨거 설치하기

다음 명령어로 스웨거를 설치합니다.

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

API 문서 작성하기

스웨거 설치가 완료됐다면 이제 다음과 같이 main.ts 파일을 업데이트해줍니다. 타이틀이나 설명 등은 프로젝트에 맞게 수정하시면 됩니다.

//main.ts

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

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

  const config = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

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

이후 서버를 실행하고 http://localhost:3000/api 로 접속하면 다음과 같이 API 문서가 자동으로 생성된 것을 볼 수 있습니다. 해당 URL은 SwaggerModule.setup('api', app, document); 부분에서 변경할 수 있습니다.

API 설명 추가하기

API에 설명을 추가할 수도 있습니다. 컨트롤러 파일로 이동하여 @ApiOperation 데코레이터를 다음과 같이 덧붙여줍니다.

//users.controller.ts

@ApiOperation({ summary: '회원가입'})
@Post()
async signUp(@Body() data: RegisterUserDto) {

  return this.usersService.register(data);
}

저장 후 다시 API 문서 페이지로 이동하면 회원가입이라는 설명이 추가된 것을 볼 수 있습니다.

예시 추가하기

Post 요청을 통한 회원가입과 같은 기능에는 어떠한 정보들을 전달해야 하는지 추가해 두는 것이 더 좋을 것입니다. 이를 위해 기존에 생성한 dto 파일로 이동하여, 다음과 같이 @ApiProperty와 속성을 추가해줍니다.

export class RegisterUserDto {
  @ApiProperty({
    example: 'hello@kakao.com',
    description: 'email',
    required: true,
  })
  @IsEmail()
  @IsNotEmpty()
  email: string;
 }

다음과 같이 기본 속성이 추가된 것을 볼 수 있습니다.

응답 코드와 설명 추가하기

응답 코드와 이에 해당하는 설명을 추가할 수도 있습니다. 컨트롤러로 이동하여 @Post() 데코레이터 위에 @ApiResponse를 다음과 같이 추가해줍니다.

 @ApiResponse({
    status: 500,
    description: 'Server Error...',
  })
  @ApiResponse({
    status: 201,
    description: 'User created!',
  })
  @ApiOperation({ summary: '회원가입' })
  @Post()
  async signUp(@Body() data: RegisterUserDto) {
    return this.usersService.register(data);
  }

이제 아래와 같이 상태 코드와 설명이 표시됩니다.

 

참고 자료

• https://docs.nestjs.com/openapi/introduction