Nest.js Swagger 사용법

Nest.js 설치 및 설정

@nestjs/swagger를 설치합니다.

yarn add @nestjs/swagger

main.ts에 swagger를 적용합니다.

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);

  const config = new DocumentBuilder()
    .setTitle('OctoDocs')
    .setDescription('OctoDocs API 명세서')
    .build();
  const documentFactory = () => SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, documentFactory);
  await app.listen(3000);
}
bootstrap();

@ApiOperation 데코레이터를 사용하면 각 api 별로 설명을 쓸 수 있습니다.

  @ApiOperation({ summary: '페이지를 생성하고 노드도 생성합니다.' })
  @Post('/')
  @HttpCode(HttpStatus.CREATED)
  async createPage(@Body() body: CreatePageDto): Promise<{ message: string }> {
    await this.pageService.createPage(body);
    return {
      message: PageResponseMessage.PAGE_CREATED,
    };
  }

다음은 request API를 표현하는 방법입니다.

dto를 사용한다면 먼저 dto의 각 필드에 대한 설명을 @ApiProperty 데코레이터를 사용하여 작성할 수 있습니다.

import { ApiProperty } from '@nestjs/swagger';
import { IsString, IsNumber, IsJSON } from 'class-validator';

export class CreatePageDto {
  @ApiProperty({
    example: 'nest.js 사용법',
    description: '페이지 제목입니다.',
  })
  @IsString()
  title: string;

  @ApiProperty({
    example: 'nest를 설치합니다.',
    description: '페이지 내용입니다.',
  })
  @IsJSON()
  content: JSON;

  @ApiProperty({
    example: '14',
    description: 'x 좌표입니다.',
  })
  @IsNumber()
  x: number;

  @ApiProperty({
    example: '14',
    description: 'y 좌표입니다.',
  })
  @IsNumber()
  y: number;
}

그 다음 컨트롤러에서 @ApiBody 데코레이터를 사용하여 dto를 넣어줍니다.

  @ApiOperation({ summary: '페이지를 생성하고 노드도 생성합니다.' })
  @ApiBody({
    description: 'post',
    type: CreatePageDto,
  })
  @Post('/')
  @HttpCode(HttpStatus.CREATED)
  async createPage(@Body() body: CreatePageDto): Promise<{ message: string }> {
    await this.pageService.createPage(body);
    return {
      message: PageResponseMessage.PAGE_CREATED,
    };
  }

다음은 ResponseApi를 사용하는 방법입니다.

마찬가지로 dto의 각 필드에 대한 설명을 쓴 다음 @ApiResponse 데코레이터의 type으로 넣어주면 됩니다.

  @ApiResponse({
    type: FindNodesResponseDto,
  })
  @ApiOperation({
    summary:
      '모든 노드 정보를 가져옵니다. (페이지 정보 중 id와 title만 가져옵니다.)',
  })
  @Get('/')
  @HttpCode(HttpStatus.OK)
  async getNodes() {
    const nodes = await this.nodeService.findNodes();
    return {
      message: NodeResponseMessage.NODE_ALL_RETURNED,
      nodes: nodes,
    };
  }