[NestJS] Parameters(매개변수)_Swagger

Swagger에서 parameters(매개변수)의 선언

SwaggerModule은 경로 핸들러에서 모든 @Body(), @Query() 및 @Param() 데코레이터를 검색하여 API 문서를 생성한다.

리플렉션(reflection)을 활용하여 해당 모델 정의를 생성한다.

@Post()
async create(@Body() createUserDto: CreateUserDto) {
  this.usersService.create(createUserDto);
}

본문 정의를 명시적으로 설정하려면 @ApiBody() 데코레이터(@nestjs/swagger 패키지)를 사용한다.

 

CreateUserDto를 기반으로 다음 모델 정의 Swagger UI가 생성된다.

CreateUserDto가 Swagger 모델(Schema)에 생성

 

export class CreateUserDto {
  name: string;

  age: number;

  major: string;
}

위와 같이 클래스에 몇 가지 선언된 속성이 있지만 정의는 비어 있을 시 Swagger 모델에 표시가 되지 않는다.

 

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

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

  @ApiProperty()
  age: number;

  @ApiProperty()
  major: string;
}

클래스 속성을 SwaggerModule에 표시하려면 @ApiProperty() 데코레이터로 주석을 달거나 자동으로 수행하는 CLI 플러그인(플러그인 섹션 참조)을 사용해야 한다.

 

* 수정 후 백엔드 서버를 껐다가 다시 켜야 Swagger에 변경 사항이 적용된다.

 

* 결과

CreateUserDto의 속성이 Swagger에 보임

 

또한 @ApiProperty() 데코레이터를 사용하면 다양한 스키마 개체 속성을 설정할 수 있다.

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

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

  @ApiProperty({
    description: 'The age of a user',
    minimum: 19,
    default: 19,
  })
  age: number;

  @ApiProperty()
  major: string;
}

 

@ApiProperty() 데코레이터의 다양한 스키마 개체 속성

 

* Parameter(매개변수)의 필수값 여부를 표현할 때
@ApiProperty({ required: false })를 명시적으로 입력하지 않아도 된다.

@ApiPropertyOptional() 데코레이터를 사용할 수 있다.

 

Parameter(매개변수)의 속성 유형을 명시적으로 설정하려면 type키를 사용한다.

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