[NestJS] 타입 종류_Swagger

NestJS 다양한 타입_Swagger에 표시하기

단순 타입 (number, string 등)

@ApiProperty({
  type: Number,
})
age: number;

@ApiProperty({
  type: String,
})
name: string;

 

 

Arrays(배열)

속성이 배열인 경우 아래와 같이 배열 유형을 수동으로 지정해야 한다.

@ApiProperty({ type: [String] })
skills: string[];

배열의 첫 번째 요소로 유형을 포함하거나(위에 표시된 대로) isArray속성을 true로 설정한다.

 

Circular dependencies(순환 종속성)

클래스 간에 순환 종속성이 있는 경우 지연 함수를 사용하여 SwaggerModule유형 정보를 제공한다.

@ApiProperty({ type: () => userStrong })
status: userStrong;

 

Generics and interfaces(제네릭과 인터페이스)

TypeScript는 제네릭 또는 인터페이스에 대한 메타데이터를 저장하지 않으므로 DTO에서 사용할 때 SwaggerModule런타임에 모델 정의를 제대로 생성하지 못할 수 있다. 

@Post()
createUser(@Body() usersDto: CreateUserDto[])

예를 들어 위 코드는 아래와 같이 Swagger 모듈에서 올바르게 검사되지 않는다.

위 코드에 대한 Swagger UI 출력값은 다음과 같다.

위 코드에 대한 Swagger 모듈 출력값

이 제한을 극복하기 위해 유형을 명시적으로 설정할 수 있다.

@ApiBody({ type: [CreateUserDto] })
@Post()
createUser(@Body() usersDto: CreateUserDto[]) {}

위 코드에 대한 Swagger UI 출력값은 다음과 같다.

위 코드에 대한 Swagger 모듈 출력값

Enums(열거형)

enum을 식별하려면 값 배열을 사용하여 enum의 속성을 @ApiProperty로 수동으로 설정해야 합니다.

@ApiProperty({ enum: ['Warrior', 'Magician', 'Thief'] })
role: UserRole;

 

또는 다음과 같이 실제 TypeScript 열거형을 정의한다.

export enum UserRole {
  Warrior = 'Warrior',
  Magician = 'Magician',
  Thief = 'Thief',
}

 

그런 다음 @ApiQuery() 데코레이터, @Query() 매개변수 데코레이터와 함께 enum을 직접 사용할 수 있다.

@ApiQuery({ name: 'role', enum: UserRole })
async filterByRole(@Query('role') role: UserRole = UserRole.User) {}

위 코드에 대한 Swagger UI 출력값은 다음과 같다.

 

enum 타입 Swagger UI

위 코드조각들 전체 모음

create-user.dto.ts

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

export enum UserRole {
  Warrior = 'Warrior',
  Magician = 'Magician',
  Thief = 'Thief',
}

export class userStrong {
  @ApiProperty({ type: Number })
  level: number;

  @ApiProperty({ enum: ['Warrior', 'Magician', 'Thief'] })
  role: UserRole;

  @ApiProperty({ type: [String] })
  skills: string[];

  @ApiProperty({ type: Number })
  magicPower: number;

  @ApiProperty({ type: Number })
  sheildPower: number;

  @ApiProperty({ type: Number })
  swordPower: number;
}

export class CreateUserDto {
  @ApiProperty({ type: String })
  name: string;

  @ApiProperty({ type: Number })
  major: number;

  @ApiProperty({ type: () => userStrong })
  status: userStrong;
}

 

user.controller.ts

import { Controller, Get, Post, Body, Query } from '@nestjs/common';
import { UserService } from './user.service';
import { CreateUserDto, UserRole } from './dto/create-user.dto';
import { ApiBody, ApiOperation, ApiQuery } from '@nestjs/swagger';

@Controller('user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post()
  @ApiBody({ type: [CreateUserDto] })
  createUser(@Body() usersDto: CreateUserDto[]) {}

  @Get()
  @ApiOperation({
    summary: `[${UserRole}] 조건에 해당하는 데이터 반환`,
  })
  @ApiQuery({ name: 'role', enum: UserRole })
  async filterByRole(@Query('role') role: UserRole = UserRole.Magician) {}
}

 

Swagger 전체 내용

Swagger 전체 내용들