[ Nest JS ] Swagger를 사용해서 API 문서 만들기

 

안녕하세요? 수구리입니다.

 

제가 최근에 Nest와 TypeORM을 사용한 백엔드 API를 만드는 강의를 듣고 있는데요~

 

API 문서를 만들어주는 Swagger라는 오픈 API가 있어서 소개해드리려고 합니다.

 

 

1단계. 공식 문서를 보자

 

무엇이든 사용하기 전에 설치 과정은 필수이죠?

 

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

Documentation | NestJS - A progressive Node.js framework

 

위의 링크를 들어가시면 NestJS에서 Swagger OpenAPI에 대해서 사용하는 방법이 나와있습니다!

 

아! 물론 한국어 공식문서도 있습니다!

 

일단, Nest 프로젝트를 생성했다고 가정하고 진행해보겠습니다.

 

 

2단계. Swagger 설치

 

공식문서를 따르면.. 

 

다음과 같이 설치를 진행하라는 명령어가 있습니다.

 

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

 

위의 명령어를 입력해서 설치를 진행해줍니다!

 

설치가 완료되면, 

 

package.json

package.json 파일에 위와 같이 설치가 완료되어집니다.

 

 

3단계. main.ts 수정하기

 

그러고 main.ts 즉, 프로젝트의 main으로 이동한 뒤에,

 

공식문서에 나와있는 대로 타이핑..!

 

 

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } 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();

 

제가 진행하고 있는 프로젝트에서는 다음과 같이 입력해주었습니다.

 

main.ts 

 

설명을 하자면, DocumentBuilder라는 객체를 config 변수에 만들어주는 건데요

 

. set 어쩌고 등등 을 통해서 객체의 속성을 지정해준다고 보시면 됩니다.

 

API 문서의 이름, 간단한 설명, 그리고 버전 마지막으로 빌드까지 수행을 해주게 되고

 

서버를 실행시켜 프로젝트의 로컬 서버로 접속을 한 뒤에, 주소창 뒤에 /api라고 입력을 한 뒤에 enter!

 

 

 

실행 결과

 

그러면 현재 제가 설계한 컨트롤러들에 대한 설명서들이 쭉 나열되어 있는 것을 볼 수 있습니다!

 

 

서버 실행 후, localhost:PORT/api 접속

 

정말 멋지지 않나요? (나만 그런가..)

 

이런 식으로 api를 잘 설계하여 front 개발자에게 또는 사용자에게 제공한다면

 

한눈에 어떤 기능을 제공하는지 알 수 있답니다.

 

저 문서에서 더 자세하게 확인도 가능합니다.

 

예를 들어 어떤 요청을 보내는지, 어떤 쿼리를 담는지, 응답은 어떻게 받을 수 있는지에 대한 내용들도 알 수 있습니다.

 

 

users.controller.ts 내용 중 로그인 관련 swagger

 

위의 부분은 users.controller.ts 내용 중 로그인에 대한 내용인데요~

 

@get, @post와 같은 @ApiOkResponse, @ApiOperation 등의 데코레이터를 활용하여 Swagger 문서를 작성할 수 있습니다.

 

login api 상세보기

 

위의 사진은 로그인에 대한 구체적인 설명들입니다.

 

데코레이터를 통해서 작성한 내용들이 들어가 있는 모습들입니다.

 

 

Swagger를 잘 사용하려면 Swagger 공식 문서도 읽어보아야겠죠..?

 

API 문서를 잘 작성하기 위해 Swagger API도 공부를 해야겠네요...

 

할 게 산더미야~

 

이상으로 Nest Js에서 Swagger API를 사용하여 내 프로젝트의 API 문서를 만들어 보았습니다

 

감사합니다!