DTO 관련 Decorator

API에서 주고 받을 모델에 대한 명세를 swagger docs에 작성할 수 있다.

@ApiProperty

Option

example
- example property를 통해 모델의 property에 대한 예시값을 보여준다.
description
- description property를 통해 property에 대한 설명을 swagger docs에서 보여준다.
required
- @ApiProerty({required: fasle}) 를 계속 입력하지 않도록 하는 @ApiPropertyOptional()이라는 단축 데코레이터가 있다.
type
- property에 대한 값의 타입을 설정할 수 있다.
- 속성이 실제로 배열일 때는 유형을 수동으로 표시해줘야 한다.
```
@ApiProperty({ type: [String] })
readonly names: string[];
```

DTO 예시

export class UserCredentialDto {
  @IsString()
  @MinLength(4)
  @MaxLength(20)
  @ApiProperty({
    example: 'aden',
    description: 'user`s name',
    required: true,
  })
  username: string;

  @IsString()
  @MinLength(4)
  @MaxLength(20
  @ApiProperty({
    example: 'Qwer1234!@',
    description: 'user`s password',
    required: true,
  })
  password: string;

	@ApiProperty({enum: ['Admin','User']})
	role: UserRole;
}

EndPoint 관련 Decorator

API에 대한 명세를 swagger docs에 작성할 수 있다.

@ApiTags

swagger에 tag를 생성해준다.

controller에 사용하면 controller에 속해있는 모든 api들이 작성한 tag의 하위에 보여지게 된다.

@ApiOperation

API 동작에 대한 설명을 추가할 수 있다.

Option

summary
- 해당 api에 대한 간략한 설명을 작성할 수 있다.

@ApiResponse

api의 response에 대한 예시 값을 swagger docs에 표시할 수 있다.

exception Filer 섹션에 정의된 일반적인 HttpException과 마찬가지로 @ApiResponse에서 상속되는 다양한 API 응답 response를 제공한다.

ApiResponses
- @ApiCreatedResponse()
- @ApiUnauthorizedResponse()
- @ApiForbiddenResponse()
- @ApiNotAcceptableResponse()
- @ApiConflictResponse()
- @ApiPayloadTooLargeResponse()
- @ApiUnprocessableEntityResponse()
- @ApiNotImplementedResponse()
- @ApiServiceUnavailableResponse()
- @ApiGatewayTimeoutResponse()
- @ApiBadGatewayResponse()
- @ApiInternalServerErrorResponse()
- @ApiUnsupportedMediaTypeResponse()
- @ApiGoneResponse()
- @ApiRequestTimeoutResponse()
- @ApiMethodNotAllowedResponse()
- @ApiNotFoundResponse()
- @ApiBadRequestResponse()
- @ApiOkResponse()

@ApiQuery

받을 query 값에 대한 명세를 표시할 수 있다.

Option

name
- query를 받은 변수의 이름을 설정할 수 있다.
type
- 어떤 type으로 query를 받을 것인지 지정할 수 있다.
enum
- enum에 지정된 값으로 제한이 된다는 것을 표시할 수 있다.
- swagger를 통해 실행할 때 enum에 해당하는 값으로 api를 실행 할 수 있다.

@ApiParam

Param으로 받을 값에 대한 명세를 표시할 수 있다.

Option

name
- parameter를 받은 변수의 이름을 설정할 수 있다.
type
- 어떤 type으로 parameter를 받을 것인지 지정할 수 있다.

@ApiBody

Body로 받을 값에 대한 명세를 표시할 수 있다.

Option

description
- body에 대한 설명을 표시할 수 있다.
type
- 입력받는 type을 표시할 수 있다.
- 만약 지정한 type(dto)에 대하여 @ApiProperty decorator를 통해 작성해 두었다면 세부정보를 swagger docs에서 확인할 수 있다.

EndPoint 예시

@ApiTags('user')
@ApiResponse({ status: 200, description: '성공' })
@ApiResponse({ status: 500, description: '내부 에러 발생' })
@Controller('user')
export class UserController {
  constructor(private userService: UserService) {}

  @ApiOperation({ summary: '회원가입' })
  @Post('/signup')
  signUp(
    @Body(ValidationPipe) userCredentialDto: UserCredentialDto,
  ): Promise<User> {
    return this.userService.signUp(userCredentialDto);
  }

  @ApiOperation({ summary: '회원정보찾기' })
  @Get('/find/:username')
  findByUsername(@Param('username') username: string) {
    return this.userService.findByUsername(username);
  }

  @Get('/')
  @ApiOperation({ summary: '전 회원 정보' })
  findAll(): Promise<User[]> {
    return this.userService.findAll();
  }
}

참고자료
https://jakekwak.gitbook.io/nestjs/recipes/untitled-4