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 출력값은 다음과 같다.
이 제한을 극복하기 위해 유형을 명시적으로 설정할 수 있다.
@ApiBody({ type: [CreateUserDto] })
@Post()
createUser(@Body() usersDto: CreateUserDto[]) {}
위 코드에 대한 Swagger UI 출력값은 다음과 같다.
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 출력값은 다음과 같다.
위 코드조각들 전체 모음
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 전체 내용
'개발 프레임워크 > NestJS' 카테고리의 다른 글
[NestJS] 개발환경 구성 (0) | 2023.02.20 |
---|---|
[NestJS] Swagger 문서 모듈 별로 분리 (0) | 2023.02.14 |
[NestJS] Type(타입)_Swagger (0) | 2023.02.09 |
[NestJS] Parameters(매개변수)_Swagger (0) | 2023.02.08 |
[NestJS] Security(보안) (0) | 2023.02.07 |
댓글