NestJS에 Swagger(스웨거) Document(문서)를 적용 - API적용

 안녕하세요. 이번에는 CRUD를 코드로 작성하면서 동시에 Swagger를 적용해서 Swagger API문서를 작성하도록 하겠습니다.

일단 가장 기본적인 API문서를 만들어보겠습니다. nestjs을 설치시 자동으로 나오는 app모듈중 'app.controller.ts'에서 아래와 같이 코드를 수정합니다.

import { Controller, Get } from '@nestjs/common';

import { ApiResponse, ApiTags } from '@nestjs/swagger';

import { AppService } from './app.service';

// ApiTags는 해당 컨트롤러의 Root경로를 입력받습니다.

@ApiTags('/')

@Controller()

export class AppController {

constructor(private readonly appService: AppService) {}

// ApiResponse는 해당 API가 응답 코드에 따른 설명을 작성합니다.

@ApiResponse({

status: 200,

description: '정상적인 GET응답',

})

@ApiResponse({

status: 500,

description: '서버에러 발생시',

})

@Get()

getHello(): string {

return this.appService.getHello();

}

}

./src/app.controller.ts

웨 코드에서 'ApiTags', 'ApiResponse' 이 2개가 추가 됬다. 이 데코레이션은 해당 Document에 관련 API정보를 보내는 것이다. 그럼 실제 출력을 보자.

그림1) rootUrl:3000/api-docs 접속 화면

 위 문서를 볼때 코드에 작성한 상태 200, 500와 그것에 대한 설명을 확인할수 있습니다. GET 메소드에는 현재 파라메타가 없기 때문에 파마메타를 추가하도록 하겠습니다.

import { Controller, Get, Param } from '@nestjs/common';

import { ApiResponse, ApiTags } from '@nestjs/swagger';

import { AppService } from './app.service';

// ApiTags는 해당 컨트롤러의 Root경로를 입력받습니다.

@ApiTags('/')

@Controller()

export class AppController {

constructor(private readonly appService: AppService) {}

// ApiResponse는 해당 API가 응답 코드에 따른 설명을 작성합니다.

@ApiResponse({

status: 200,

description: '정상적인 GET응답',

})

@ApiResponse({

status: 500,

description: '서버에러 발생시',

})

@Get(':id')

getHello(@Param('id') id: number): string {

return this.appService.getHello(id);

}

}

./src/app.controller.ts

GET요청에 id 파라메타를 추가해 줍니다. 동시에 appService에 있는 getHello메소드에서도 id값을 받을수 있게 합니다.

import { Injectable } from '@nestjs/common';

@Injectable()

export class AppService {

getHello(id: number): string {

return `Hello World! Num : ${id}`;

}

}

./src/app.service.ts

그림2) 파라메타 적용후

위와 같이 코드에 파라메타를 받을수 있게 적용후 Swagger 문서에서 파라메타의 id를 받을수 있는 방법에 대해 작성이 되어있는것을 알수있습니다. 

그럼 다음에는 실제 CRUD와 DTO를 작성하고 Swagger를 적용하도록 하겠습니다.

(이전글)