[NestJS 프로젝트 문서화 1] Swagger API란?

Swagger API란?

---

Swagger는 팀과 개인을 위한 강력하면서도 사용하기 쉬운 API 개발자 도구 제품군으로, 웹 사이트 설계 및 문서화부터 테스트 및 배포에 이르기까지 웹 사이트 개발 전체 수명 주기에 걸쳐 기능을 제공하는 오픈 소스 도구입니다.

 

Swagger는 다음과 같은 특징들을 가지고 있습니다.

• 표준화: Swagger는 표준화된 API 문서화를 제공합니다. 이는 개발자 간의 협업을 용이하게 하며, API를 사용하는 클라이언트 개발에도 효율적입니다.
• 자동화: Swagger는 API 엔드포인트, 요청 형식, 응답 형식 등에 대한 자세한 정보를 자동으로 생성합니다. 이로 인해 개발자는 수동으로 API 문서를 작성하거나 업데이트하는 데 드는 시간을 절약할 수 있습니다.
• 호환성: Swagger는 다양한 플랫폼 및 언어와 호환됩니다. Java, Python, Node.js, Ruby 등 다양한 언어로 작성된 API에 대해 Swagger를 사용할 수 있습니다.
• 사용자 경험: Swagger는 직관적인 사용자 인터페이스를 제공합니다. 이를 통해 개발자는 API의 동작을 쉽게 이해할 수 있으며, 실시간으로 API를 테스트하고 결과를 확인할 수 있습니다.
• 커뮤니티: Swagger는 활발한 오픈 소스 커뮤니티를 바탕으로 지속적으로 발전하고 있습니다. 이로 인해 새로운 기능이 지속적으로 추가되며, 발생 가능한 이슈에 대해서도 빠르게 대응할 수 있습니다.

NestJS에서 Swagger API 이용

---

우선 터미널에 아래 명령어를 이용하여 프로젝트에 swagger 모듈을 다운로드 받아줍니다.

npm install --save @nestjs/swagger

 

swagger.ts

import { INestApplication } from "@nestjs/common";
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";

export function setupSwagger(app: INestApplication) {
    const options = new DocumentBuilder()
        .setTitle('NestJS API')
        .setDescription('NestJS API description')
        .setVersion('1.0.0')
        .addTag('nestjs')
        .build();

    const document = SwaggerModule.createDocument(app, options);
    SwaggerModule.setup('api', app, document);
}

 

필자는 src안에 util 디렉토리를 따로 생성 후 해당 디렉토리에 swagger.ts를 따로 생성하였습니다.

 

SwaggerModuel.setup()에서 SwaggerUI를 마운트 할 수 있는 경로를 따로 지정할 수 있습니다. 본 문서에서는 /api 로 설정하였습니다.

 

main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { setupSwagger } from './util/swagger'

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

  // Swagger API 문서 생성 및 설정
	setupSwagger(app);

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

 

main.ts에 Swagger API를 실행시키는 코드를 추가해줍니다.

 

 

 

http://localhost:3000/api 로 접속하게 된다면 위와 같이 Swagger API 페이지로 접속 되는 것을 확인할 수 있습니다.

DocumentBuilder()

---

const options = new DocumentBuilder()
        .setTitle('제목') //api 페이지 제목 추가
        .setDescription('설명') //설명 추가
        .setVersion('1.0.0') // API 버전 선택
        .addTag('그룹') //그룹 추가
        .build(); //문서 생성

 

DoucmentBuilder()는 문서의 기본을 구성할 수 있게 해주는 클래스입니다. 문서 생성 시에 포함할 수 있는 옵션은 여러가지가 존재하며 가장 기본적인 사항은 위와 같습니다. .build()를 제외한 나머지 메서드는 없어도 정상 동작하며 버전을 따로 선택하지 않을 시 기본 1.0.0으로 api가 실행되게 됩니다.

 

DocumentBuilder()에서 지원하는 주요 메서드는 아래와 같습니다.

.setTitle()

Swagger 문서의 제목을 설정합니다. 이는 사용자가 Swagger UI를 통해 볼 수 있는 문서의 제목이 됩니다.

.setDescription()

API에 대한 간략한 설명을 추가합니다.

.setVersion()

API의 버전 정보를 설정합니다.

.setTag()

API를 로직별로 분류할 수 있는 태그를 추가합니다. description과 externalDocs는 선택적입니다.

더 많은 메서드는 아래 문서를 참고바랍니다.