[NestJS] Swagger(스웨거)란?

NestJS 형상관리 도구_스웨거(Swagger)

Swagger(스웨거)는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크라고 설명하지만 쉽게 말하면

 

 Swagger는 API 문서 자동화 도구이다.

 

1. API 문서를 따로 작성할 필요 없다.

2. 만약에 코드와 API 문서를 따로 관리하게 되면 코드를 수정하였는데 API 문서 최신화를 잊어버려서 다른 팀원들에게 공유된 API 문서가 실제 API와 다른 문제가 발생할 수 있다.

 ->  스웨거를 사용한다면 NestJS에서 코드를 수정하면서 API 문서를 같이 수정할 수 있다.

3. 다른 장점으로는 Swagger는 API를 테스트할 수 있는 GUI를 제공한다.

 

NestJS에서 Swagger 설치하는 방법

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

 

NestJS(fastify)를 사용하는 경우 Swagger 설치하는 방법

npm install --save @nestjs/swagger fastify-swagger

 

Swagger를 사용하기 위해서 main.ts에서 설정을 해주어야 한다.

 

main.ts

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

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

  // Swagger 문서툴 설정
  const swaggerConfig = new DocumentBuilder()
    .setTitle('API server')
    .setDescription("The API server's API description")
    .setVersion('1.0')
    .build();
  const document = SwaggerModule.createDocument(app, swaggerConfig);
  SwaggerModule.setup('api', app, document);

  // 서버 실행
  await app.listen(3000);
}
bootstrap();

L10: DocumentBuilder() 객체를 생성할 때 제목, 설명 , 버전, 태그(.addTag)등을 설정해준다.

L16: 주소 뒤에 /api를 붙이면 Swagger가 실행되게 설정한다. 'api'가 아나리 'apiDoc'이라고 하면 주소뒤에 /apiDoc을 붙이듯이 본인에게 맞게 설정하면 된다.

 

HTTP서버 실행 명령어

$ npm run start

 

실행주소: http://localhost:3000/api

Swagger 타이틀 및 버전 정보

Swagger를 실행하면 상단 부에 DocumentBuilder() 객체를 생성할 때 제목, 설명 , 버전등을 설정했던 정보들이 나온다.

 

 

Swagger C R U D

아래로 내려보면 본인이 만든 백엔드 API들을 Swagger를 통해 확인해볼 수 있다 .

여기서 POST, GET, PUT, DELETE, PATCH등을 확인해 볼 수 있는데 잘 동작한다면 API에는 문제가 없는 것이고 보통 Front-End에서 받아올 때 잘 못 받아오거나 양쪽 환경설정이 안 맞거나 한쪽이 잘못되어 있을 가능성이 크다.

 

 

Swagger Models

맨 아래로 내리면 Models를 확인해볼 수 있는데 작업도중에 모델의 속성이 변경되거나 하면 항상 통일 시켜주는 것이 중요하다 .

 

 

결론: NestJS에서 Swagger를 통해 형상관리를 하면 동시에 할 수 있어서 최신화하기 편하다. 잘 써보자.