Nestjs 프로젝트에서 Swagger 사용하기

https://swagger.io/

NestJS는 모듈 기반의 프레임워크로, RESTful API 개발에 최적화되어 있습니다. 특히 Swagger를 사용하면 API 문서를 자동으로 생성하고, 이를 통해 API를 테스트하거나 협업에 활용할 수 있습니다. 이 글에서는 NestJS 프로젝트에 Swagger를 설정하고 사용하는 방법을 알아봅시다!

 

1. Swagger란?

Swagger는 OpenAPI 명세를 바탕으로 API 문서를 자동 생성해주는 도구입니다. 개발자와 비개발자 모두가 API의 기능과 사용 방법을 직관적으로 이해할 수 있게 도와줍니다. NestJS에서는 @nestjs/swagger 패키지를 사용하여 쉽게 API 문서를 생성할 수 있습니다.

2. NestJS 프로젝트에 Swagger 설치하기

먼저, Swagger 관련 패키지를 설치해야 합니다. 아래 명령어로 패키지를 설치합니다.

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

@nestjs/swagger는 Swagger를 NestJS에 통합하기 위한 패키지이며, swagger-ui-express는 브라우저에서 API 문서를 확인할 수 있는 UI를 제공합니다.

3. Swagger 설정하기

Swagger를 사용하려면, NestJS 애플리케이션에서 Swagger 설정을 해줘야 합니다.
기본적인 설정은 main.ts 파일에서 이루어집니다.

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

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

  // Swagger 설정
  const config = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('API Documentation')
    .setVersion('1.0')
    .addTag('cats')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api-docs', app, document);

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

위 코드에서 DocumentBuilder()를 사용하여 Swagger 문서의 제목, 설명, 버전 등을 설정합니다. SwaggerModule.setup()은 Swagger UI가 제공되는 경로를 설정합니다. 위 예시에서는 /api-docs 경로에서 API 문서를 확인할 수 있습니다.

npm run start

http://localhost:3000/api-docs로 들어가면 swagger 문서를 보실 수 있습니다!

4. API 문서 작성하기

이제 각 컨트롤러와 DTO에 Swagger 데코레이터를 추가하여 더 상세한 API 문서를 작성할 수 있습니다. 예를 들어, 다음과 같이 @ApiTags()와 @ApiProperty()를 사용하여 문서를 작성할 수 있습니다.
컨트롤러에만 Swagger를 사용하고 Swagger UI를 간단하게 확인해 볼 수 있습니다.

 

CatsController 파일 생성: src 디렉토리 내에 cats라는 폴더를 만들고, 그 안에 cats.controller.ts 파일을 생성

import { Controller, Get, Post, Body } from '@nestjs/common';
import { ApiTags, ApiProperty } from '@nestjs/swagger';

class CreateCatDto {
  @ApiProperty({ example: 'rem', description: 'The name of the cat' })
  name: string;

  @ApiProperty({ example: 3, description: 'The age of the cat' })
  age: number;
}

@ApiTags('cats')
@Controller('cats')
export class CatsController {
  @Get()
  findAll() {
    return 'This action returns all cats';
  }

  @Post()
  create(@Body() createCatDto: CreateCatDto) {
    return 'This action adds a new cat';
  }
}

• @ApiTags()는 컨트롤러 레벨에서 태그를 추가하여 문서에서 API를 그룹화할 수 있습니다.
• @ApiProperty()는 DTO 속성에 대한 설명을 작성하여 Swagger UI에서 보다 자세한 정보를 제공할 수 있습니다.

모듈에 CatsController 등록: src/app.module.ts 파일을 열고 CatsController를 등록합니다.

import { Module } from '@nestjs/common';
import { CatsController } from './cats/cats.controller';

@Module({
  imports: [],
  controllers: [CatsController],
  providers: [],
})
export class AppModule {}

5. 결과 확인하기

이제 애플리케이션을 실행하고 /api-docs로 접속하면, Swagger UI에서 API 문서를 확인하고 직접 API 요청을 테스트할 수 있습니다.

npm run start

브라우저에서 http://localhost:3000/api-docs로 접속하면, 다음과 같은 화면을 볼 수 있습니다.

 Try it out 버튼을 클릭하면 API의 동작을 테스트할 수 있는 화면이 나옵니다.

@ApiTags()로 ‘CAT API’를 설정하였는데, 해당 컨트롤러가 어떤 API인지 구분할 수 있습니다.
각 API에 대한 설명은 @ApiOperation()으로 설정할 수 있으며, @ApiCreatedResponse()와 같은 데코레이터를 사용하여 API 응답 형식을 정의할 수 있습니다.

예를 들어, CatsController는 고양이에 대한 정보를 처리하는 API로, findAll 메서드는 모든 고양이의 목록을 반환하고, create 메서드는 새로운 고양이를 생성하는 기능을 제공한다. 각 메서드에 대한 설명과 응답 구조를 Swagger 데코레이터를 통해 명확히 할 수 있습니다.

 

마치며

Swagger를 사용하지 않고 Wiki와 같은 플랫폼을 통해 API 문서를 관리하는 것은 Swagger보다 유연한 문서 제공이 가능하게 합니다. 하지만 Wiki를 이용할 경우, 코드 수정이 발생할 때마다 문서를 최신 상태로 유지하는 것을 반드시 염두에 두어야 합니다. 또한, Postman과 같은 API 테스트 도구를 제공하여 사용자들이 쉽게 API를 검증할 수 있도록 해야 합니다.

 

더 많은 @nestjs/swagger의 데코레이터들은 여기에서 확인할 수 있으며, 공식 문서 내 OPENAPI 섹션에서도 유용한 추가 정보를 얻을 수 있습니다!

 

 

Reference

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