[NestJS] 프로젝트에서 사용한 swagger 태그

프로젝트 진행 중 작성한 wiki 를 옮겨와 편집했습니다.

 

팀원들 고생하지 말라고 필수적인 태그만 정리한 거라 부족한 점이 많습니다.
Nest 와 Swagger 공식문서를 보면서 태그 쇼핑하시는 것을 추천합니다.
하지만 제가 프로젝트 시작할 때는 다른 사람들이 대체 무슨 태그를 쓰는 지 궁금했어서 기록용으로 남깁니다...ㅎㅎ

 

ApiOperation

Api에 대한 설명을 적는 태그입니다.

 

사용 예

@ApiOperation({ summary: '친구 신청하기 (닉네임)' })

 

적용 스크린샷

Path 옆에 summary 의 내용이 나타납니다.
메소드 위에 주석 (/**/) 을 쓰면 더 상세한 표기가 가능합니다. (Nest 의 swagger plugin 을 적용했을 경우)

 

Api{StatusCode}Response

status code 는 "NotFound"(404) 나 "BadRequest"(400) 등의 형태로 들어갑니다.
저는 에러 코드 응답 중에서도 서버 로직에서 나는 에러는 제외하고 클라이언트에서 날 수 있는 것만 표시했습니다.
모든 경우의 수를 다 적으면 지저분해지기 때문에 어느정도만 쓰시는 것을 추천합니다..

 

사용 예

@ApiConflictResponse({
  type: ErrorResponseDto,
  description: '신청 정원 초과, 이미 친구 상태, 이미 친구 신청 상태, 자기 자신에게 신청',
})
@ApiNotFoundResponse({ type: ErrorResponseDto, description: '유저 없음' })

 

적용 스크린샷

Status code 별로 다 있습니다.

 

APIQuery, ApiHeaders, ApiParam

api 에 header, param, querystring이 필요해!!!! 할 때 사용합니다.
제가 진행했던 프로젝트에서는 로그인 기능 적용 전 임시 헤더로 user id 를 주고받아서 모든 api에 @ApiHeaders 를 사용했습니다.

 

사용 예

@ApiQuery({ name: 'nickname', description: '친구 신청할 유저의 닉네임' })
@ApiHeaders([{ name: 'x-my-id', description: '내 아이디 (임시값)' }])

 

적용 스크린샷

 

사용 예

@ApiParam({ name: 'userId', description: '친구 신청할 유저의 아이디' })

 

적용 스크린샷

 

이 태그들을 달면 테스트 시 값 입력을 요구하는 데, required: false 를 추가하면 값을 넣지 않아도 테스트 할 수 있습니다.

 

DTO 는 어쩌죠?

⇒ (Nest 의 swagger plugin 을 적용했을 경우) 파일명이 .dto.ts 이면 알아서 detect 해줍니다.

주석으로 상세 설명이 가능합니다.

 

사용 예

export class SuccessResponseDto {
  constructor(msg: string) {
    this.message = msg;
  }
  /**
   * 성공 응답 메세지
   * @example '요청이 처리되었습니다.'
   */
  message: string;
}

프로퍼티 위 주석 정보를 읽어서 swagger 에 심어줍니다.
@example 로 예시를 넣을 수 있습니다.

 

적용 스크린샷

 

api 응답에서도 리턴되는 dto type 의 @example 값을 읽어 example value 로 넣어줍니다.

 

주의

object literal 의 배열은 인식하지 못합니다.

 

뭔가 참조 문제가 나는데 swagger cli 에서 나는 문제라 디버깅이 어려워서 그냥 타입을 따로 선언하고 type[] 하는 식으로 해결했습니다.

 

그래서 어떻게 썼는데?

  @ApiOperation({ summary: '로그인 2단계 인증' })
  @ApiHeaders([{ name: 'x-my-id', description: '내 아이디 (임시값)' }])
  @ApiForbiddenResponse({ type: ErrorResponseDto, description: '유효하지 않은 인증 코드' })
  @ApiBadRequestResponse({ type: ErrorResponseDto, description: '잘못된 인증 코드' })
  @SkipUserGuard()
  @UseGuards(TwoFaGuard)
  @HttpCode(HttpStatus.OK)
  @Post('login/2fa')
  async twoFactorAuthLogin(
    @ExtractUserId() myId: number,
    @Body() { code }: CodeVerificationRequestDto,
    @Res() res: Response,
  ): Promise<void> {
	...
  }

더 많은 예시는 github 을 참고해 주세요