NestJS에서 API 엔드포인트와 Swagger 데코레이터 활용
Swagger
API 문서화와 테스트를 지원하는 도구로, API의 구조와 사용법을 시각적으로 표현하여 개발자와 클라이언트가 API를 쉽게 이해하고 활용할 수 있게 한다.
Swagger의 주요 기능
- 자동화된 API 문서 생성: Swagger는 API의 엔드포인트, 요청 및 응답 구조를 기반으로 자동으로 문서를 생성한다.
- 인터랙티브 API 테스트: Swagger UI를 통해 API 엔드포인트를 직접 테스트하고, 요청을 보내고 응답을 받을 수 있다.
- 클라이언트 코드 생성: Swagger는 API 문서를 바탕으로 클라이언트 SDK를 자동으로 생성하여, 다양한 프로그래밍 언어와 플랫폼에서 API를 쉽게 사용할 수 있게 한다.
- 명확한 API 정의: Swagger는 API의 요청 및 응답 데이터 형식, HTTP 메서드, 상태 코드 등을 명확하게 정의하여, API 사용 시 혼동을 줄인다.
API와 엔드포인트의 개념
API (Application Programming Interface):
소프트웨어 간의 상호작용을 정의하는 인터페이스로, 클라이언트와 서버 간의 데이터 교환을 허용하며, 요청과 응답의 형식을 규정한다.
엔드포인트
API에서 특정 기능을 제공하는 URL 경로, 각 엔드포인트는 특정 HTTP 메서드와 함께 사용되며, 클라이언트의 요청을 서버에서 처리하는 지점을 정의한다.
주요 데코레이터 설명
@Post('/path')
메서드가 지정된 경로로 들어오는 POST 요청을 처리하도록 지정한다.
POST 요청은 일반적으로 서버에 데이터를 제출할 때 사용됩니다.
@ApiOperation({ summary: 'Operation Description' })
Swagger 문서에서 메서드의 목적을 설명하는 데 사용된다.
API 문서에서 메서드의 기능을 쉽게 이해할 수 있게 한다.
@ApiOkResponse({ description: 'Success Description', type: ResponseType })
요청이 성공적으로 처리되었을 때 반환되는 응답의 타입과 설명을 정의한다.
성공 시 지정된 데이터 타입이 반환됨을 명시한다.
@ApiBadRequestResponse({ description: 'Bad Request Description' })
요청이 잘못되었을 때 반환되는 응답을 정의한다.
클라이언트가 제공한 데이터가 유효하지 않은 경우 이 응답이 반환된다.
@UsePipes(ValidationPipe)
요청 데이터의 유효성을 검증하기 위해 사용된다.
ValidationPipe는 DTO(Data Transfer Object)를 검증하여 유효하지 않은 데이터가 서버로 전달되는 것을 방지한다.
@AuditLog(AuditLogAction.ActionType)
메서드에서 발생한 작업을 감사 로그에 기록한다.
특정 작업 유형으로 기록되며, 이를 통해 작업의 이력을 추적할 수 있게 한다.
@ApiHeader({ name: 'Header-Name', description: 'Header Description', required: false })
요청 헤더 중 지정된 값을 가져온다.
이 값은 선택적이며, 인증이나 다른 목적으로 사용될 수 있다.
헤더는 클라이언트와 서버 간의 인증 및 데이터 교환을 지원한다.
@UseGuards(AuthGuard)
인증 및 권한 관리를 처리하기 위해 사용된다.
AuthGuard를 통해 요청이 인증된 사용자에게만 허용되도록 하며, 보안을 강화한다.
@ApiBody({ type: CreateDto })
요청 본문(body)에 포함된 데이터의 형식을 정의한다.
@Catch(HttpException)
에러 처리 핸들러를 정의한다.
HttpException을 통해 발생할 수 있는 예외를 처리하며, 클라이언트에게 적절한 오류 메시지를 반환한다.
@Cacheable()
응답 데이터를 캐싱하여 성능을 최적화한다.
자주 요청되는 데이터를 캐시하여 서버의 부하를 줄이고 응답 시간을 단축시킨다.
SwaggerModule.createDocument()
Swagger 문서를 자동으로 생성한다.
API의 구조와 사용법을 문서화하여, 개발자와 클라이언트가 API를 이해하고 활용하는 데 도움을 준다.
