[Nest.js] swagger 데코레이터 - 2 (응답 데코레이터)

1. @ApiResponse()

- 용도: 모든 유형의 API 응답을 정의할 수 있는 일반적인 데코레이터

@ApiResponse({
  status: 201,                         // HTTP 상태 코드
  description: '게시글 생성 성공',       // 응답 설명
  type: PostResponseDto,              // 응답 타입 (DTO)
  schema: {                           // 복잡한 응답 스키마 정의 시
    example: {
      id: 1,
      title: '제목',
      content: '내용'
    }
  }
})

 

2. @ApiOkResponse()

- 용도: 200 성공 응답 정의

@ApiOkResponse({
  description: '게시글 목록 조회 성공',
  type: PostListResponseDto,
  isArray: true                      // 배열 응답인 경우
})

 

3. @ApiCreatedResponse()

- 용도: 201 생성 성공 응답 정의

@ApiCreatedResponse({
  description: '새 게시글 생성 완료',
  type: PostResponseDto,
  schema: {
    example: {
      id: 1,
      createdAt: '2024-01-01T00:00:00Z'
    }
  }
})

 

4. @ApiZBadRequestResponse()

- 용도: 400 잘못된 요청 응답 정의

@ApiBadRequestResponse({
  description: '잘못된 입력값',
  schema: {
    example: {
      statusCode: 400,
      message: ['title must not be empty'],
      error: 'Bad Request'
    }
  }
})

 

5. @ApiUnauthorizedResponse()

- 용도: 401 인증 실패 응답 정의

@ApiUnauthorizedResponse({
  description: '인증 실패',
  schema: {
    example: {
      statusCode: 401,
      message: 'Unauthorized'
    }
  }
})

 

6. @ApiForbiddenResponse()

- 용도: 403 권한 없음 응답 정의

@UseGuards(RolesGuard)
@ApiForbiddenResponse({
  description: '접근 권한 없음',
  schema: {
    example: {
      statusCode: 403,
      message: '이 작업에 대한 권한이 없습니다.'
    }
  }
})