Nestjs 에서 Swagger 사용하기

generate swagger ui

 

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

 

 

main.ts 에 다음과 같이 작성합니다.

 

 

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

// nsetjs hot reloading setup
declare const module: any;

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

  const config = new DocumentBuilder()
    .setTitle('Sleact API')
    .setDescription('Dev sleact docs')
    .setVersion('1.0')
    .addCookieAuth('connect.sid')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  const port = process.env.PORT || 3000;
  await app.listen(port);
  console.log(`listening to port: ${port}`);

  if (module.hot) {
    module.hot.accept();
    module.hot.dispose(() => app.close());
  }
}
bootstrap();

 

 

서버 실행후 http://localhost:8080/api/ 접속 합니다.

 

 

 

 

하지만 api 내부내용 과 dto 에 관련된것들은 아직 비어 있습니다.

 

 

설명 달아주기

 

 

users.controller.ts로 이동하여 해당 api 에 설명을 달아보겠습니다.

 

 

import { Body, Controller, Get, Post } from '@nestjs/common';
import { ApiOperation } from '@nestjs/swagger';
import { JoinRequestDto } from './dto/join.request.dto';
import { UsersService } from './users.service';

@Controller('api/users')
export class UsersController {
  constructor(private usersService: UsersService) {}
  @ApiOperation({ summary: '내정보 조회' })
  @Get() // Get /users/
  getUsers() {}

  @ApiOperation({ summary: '회원가입' })
  @Post() // Post /users/
  postUsers(@Body() data: JoinRequestDto) {}

  @ApiOperation({ summary: 'login' })
  @Post('login') // Post /users/login/
  login() {}

  @ApiOperation({ summary: 'logout' })
  @Post('logout') // Post /users/logout/
  logOut() {}
}

 

 

ApiOperation 데코레이터를 사용해 key 로 summary, value 로 설명을 적어주면 설명이 업데이트 됩니다.

 

 

 

 

dto swagger 연동하기

 

 

users/dto/join.request.dto.ts 로 이동하여 다음과 같이 수정합니다.

import { ApiProperty } from '@nestjs/swagger';

export class JoinRequestDto {
  @ApiProperty({
    example: 'popawaw@naver.com',
    description: 'email',
    required: true,
  })
  public email: string;
  @ApiProperty({
    example: '하종윤',
    description: '닉네임',
    required: true,
  })
  public nickname: string;
  @ApiProperty({
    example: '1234',
    description: 'password',
    required: true,
  })
  public password: string;
}

 

 

 

 

ApiProperty 데코레이터를 type definition 을 통해서 어떠한 옵션을 줄수 있는지 확인 할수 있습니다.

예제를 잘적어주는 것이 문서를 보고 협업하는데 좋을거 같네요

 

 

 

 

 

 

 

Query 와 Param swagger 연동하기

 

 

users.controller.ts 로 이동하여 다음과 같이 수정합니다.

 

 

import { Controller, Get, Param, Post, Query } from '@nestjs/common';
import { ApiParam, ApiQuery } from '@nestjs/swagger';
import { query } from 'express';

@Controller('api/workspaces/:url/dms')
export class DmsController {
  @ApiParam({
    name: 'url',
    required: true,
    description: 'workspace url',
  })
  @ApiQuery({
    name: 'perPage',
    required: true,
    description: '한번에 가져오는 개수',
  })
  @ApiQuery({
    name: 'page',
    required: true,
    description: '불러올 페이지',
  })
  @Get(':id/chats')
  getChat(@Query() query, @Param() param) {
    console.log(query.perPage, query.page);
    console.log(param.id, param.url);
  }

  @Post(':id/chats')
  postChat() {}
}

 

 

Tag 로 그룹화 하기

 

 

공통되는 api 들을 태그를 사용하여 하나의 그룹으로 분리 할수 있습니다.

 

 

 

 

Controller 데코레이터 위에 ApiTags 를 사용하여 분리 할 수 있습니다.

 

 

공통되는 response 타입 만들어서 swagger 와 연동하기

 

 

다른 controller 에서도 공통적으로 사용될 거 같은 dto 를 common 폴더를 만들어서 사용합니다.

 

 

 

 

/src/common/dto/user.dto.ts

import { ApiProperty } from '@nestjs/swagger';
import { JoinRequestDto } from 'src/users/dto/join.request.dto';

export class UserDto extends JoinRequestDto {
  @ApiProperty({
    required: true,
    example: 1,
    description: 'user id',
  })
  id: number;
}

 

 

일전에 만들어 두었떤 JoinReqeustDto class 를 상속받아 UserDto 를 만듭니다.

 

 

users.controller.ts

 

 

...
@ApiOperation({ summary: 'login' })
  @ApiResponse({
    type: UserDto,
    description: 'success',
    status: 200,
  })
  @Post('login') // Post /users/login/
  login() {}
...

 

 

ApiResponse 를 사용하여 type 에 dto 타입을 명시하고 status code 와 설명을 명시합니다.

 

 

 

 

dto 를 클래스로 만들면 좋은점은 interface 는 javascript 로 빌드되는 과정에서 사라지지만 class 는 사라지지 않고 어느정도의 타입역활을 해줄 수 있습니다.

 

그리고 validation 라이브러리를 사용하여 타입 체킹도 가능합니다.

 

깃허브 주소 참고하기

 

https://github.com/JongyunHa/sleack-backend/commit/3d6bcdf8fc1b45a658a3520e9385187e7f5502cd

connection nest swagger ui · JongyunHa/sleack-backend@3d6bcdf