NestJS + Swagger Decorator

swagger 관련 대표적인 decorator에 대한 설명입니다.

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