[typescript] 타입스크립트로 Nest.js Swagger 문서화하기

11 Dec 2023

typescript

Nest.js는 TypeScript로 구축된 서버 사이드 애플리케이션을 위한 프레임워크로, 네이티브로 빠른 성능을 제공하며 강력한 모듈 시스템을 갖추고 있습니다. Swagger는 API 문서 생성을 위한 강력한 도구로, 사용자 친화적인 인터페이스를 통해 API 엔드포인트 및 데이터 모델을 시각화할 수 있습니다. 이번 글에서는 Nest.js와 Swagger를 결합하여 API를 문서화하는 방법을 살펴보겠습니다.

Nest.js 프로젝트 생성

먼저 Nest.js 프로젝트를 생성해야 합니다. 아래 명령어를 사용하여 Nest.js CLI를 전역으로 설치한 후, 프로젝트를 생성합니다.

$ npm install -g @nestjs/cli
$ nest new my-api-project

Swagger 모듈 설치

Nest.js 프로젝트에서 Swagger를 사용하기 위해서는 @nestjs/swagger 패키지를 설치해야 합니다.

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

Swagger 모듈 설정

다음으로, main.ts 파일에서 Swagger 모듈을 설정해야 합니다. @nestjs/swagger 패키지에서 SwaggerModule와 DocumentBuilder를 가져와서 API 문서를 생성합니다.

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 options = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('My API description')
    .setVersion('1.0')
    .addTag('my-api')
    .build();
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('api', app, document);

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

컨트롤러 및 DTO 작성

Nest.js에서 API를 만들기 위해서는 컨트롤러와 DTO(Data Transfer Object)를 작성해야 합니다. 아래는 예시 코드입니다.

// sample.controller.ts
import { Controller, Get, Post, Body } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiCreatedResponse, ApiBody } from '@nestjs/swagger';

import { CreateSampleDto, SampleDto } from './sample.dto';

@ApiTags('samples')
@Controller('samples')
export class SampleController {
  @ApiOperation({ summary: 'Get all samples' })
  @ApiCreatedResponse({ description: 'Return all samples' })
  @Get()
  findAll(): SampleDto[] {
    // Your code here
  }

  @ApiOperation({ summary: 'Create a sample' })
  @ApiCreatedResponse({ description: 'The sample has been successfully created' })
  @ApiBody({ type: CreateSampleDto })
  @Post()
  create(@Body() createSampleDto: CreateSampleDto): SampleDto {
    // Your code here
  }
}

// sample.dto.ts
import { ApiProperty } from '@nestjs/swagger';

export class CreateSampleDto {
  @ApiProperty()
  readonly name: string;

  @ApiProperty()
  readonly description: string;
  
  // Your code here
}

export class SampleDto {
  @ApiProperty()
  readonly name: string;

  @ApiProperty()
  readonly description: string;
  
  // Your code here
}

서버 실행 및 Swagger 확인

이제 프로젝트를 실행한 후 http://localhost:3000/api로 접속하여 Swagger UI를 확인할 수 있습니다. Swagger UI에서는 API 엔드포인트와 각 엔드포인트에 대한 설명을 확인할 수 있습니다.

이처럼 Nest.js와 Swagger를 함께 사용하면 API를 빠르게 문서화하고 사용자 친화적인 인터페이스를 제공할 수 있습니다.

참고 문헌:

이상으로 Nest.js와 Swagger를 사용하여 API를 문서화하는 방법을 알아보았습니다.