TIL - 20260306

0306 NestJS 심화 (6/N): API 문서화(Swagger)와 헬스 체크(Terminus)

---

✅ 1. Swagger (OpenAPI): API 문서 자동화

• Swagger는 OpenAPI Specification(OAS) 표준을 기반으로, REST API의 명세를 자동으로 생성하고, 시각적인 UI로 문서화하며, 해당 UI에서 직접 API를 테스트해볼 수 있는 강력한 도구입니다.

• 문제점: API를 개발한 후, API 명세서를 별도의 문서(Wiki, Excel 등)로 관리하면, 코드 변경 사항이 문서에 제때 반영되지 않아 결국 코드와 문서가 불일치하게 되는 문제가 발생합니다.

• Swagger의 해결책: 코드가 곧 문서(Code as Documentation)가 되도록 합니다. 코드에 추가한 데코레이터를 기반으로 항상 최신 상태의 API 문서를 자동으로 생성해줍니다.

➕ NestJS와 Swagger 연동 (@nestjs/swagger)

1. 패키지 설치:

   npm install @nestjs/swagger

2. main.ts에 설정 추가:

   • SwaggerModule을 사용하여 Swagger 문서를 생성하고, 특정 경로(e.g., /api-docs)에 UI를 설정합니다.

   // main.ts
   import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
   
   async function bootstrap() {
     const app = await NestFactory.create(AppModule);
   
     const config = new DocumentBuilder()
       .setTitle('My API')
       .setDescription('The API description')
       .setVersion('1.0')
       .addTag('movies') // API 그룹 태그
       .build();
     
     const document = SwaggerModule.createDocument(app, config);
     SwaggerModule.setup('api-docs', app, document); // /api-docs 경로에 Swagger UI 생성
   
     await app.listen(3000);
   }
   bootstrap();

➕ 주요 데코레이터로 문서 상세화

• 컨트롤러와 DTO에 데코레이터를 추가하여, 자동 생성된 문서의 가독성과 상세함을 높일 수 있습니다.

  • @ApiTags(): 컨트롤러를 특정 태그(그룹)에 포함시킵니다.
  • @ApiOperation(): 각 API 엔드포인트의 기능에 대한 요약(summary) 및 설명(description)을 추가합니다.
  • @ApiResponse(): 발생 가능한 응답 상태 코드별로 설명을 추가합니다.
  • @ApiProperty(): DTO나 엔티티의 각 필드에 대한 설명과 예시를 추가합니다.

  // movies.controller.ts
  import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
  
  @ApiTags('movies')
  @Controller('movies')
  export class MoviesController {
  
    @ApiOperation({ summary: 'Create a movie', description: 'Creates a new movie record.' })
    @ApiResponse({ status: 201, description: 'Successfully created.'})
    @ApiResponse({ status: 400, description: 'Invalid input.'})
    @Post()
    create(@Body() createMovieDto: CreateMovieDto) { ... }
  }

---

✅ 2. 헬스 체크 (Health Check)

• 헬스 체크란 애플리케이션과 그 의존성(데이터베이스, 외부 API 등)이 정상적으로 동작하고 있는지를 외부에서 확인할 수 있도록, 간단한 상태 정보를 제공하는 엔드포인트(/health)를 만드는 것입니다.

• 왜 필요한가?:

  • 자동화된 모니터링: 로드 밸런서(AWS ALB 등)나 컨테이너 오케스트레이터(Kubernetes)와 같은 외부 시스템이 이 헬스 체크 엔드포인트를 주기적으로 호출합니다.
  • 장애 감지 및 자동 복구: 만약 헬스 체크가 실패하면(e.g., DB 연결 끊김), 외부 시스템은 해당 애플리케이션 인스턴스에 문제가 발생했다고 판단하고, 다음과 같은 조치를 자동으로 수행합니다.
    • 로드 밸런서는 해당 인스턴스로 더 이상 트래픽을 보내지 않습니다.
    • Kubernetes는 문제가 발생한 Pod를 종료하고, 건강한 새 Pod를 자동으로 생성합니다.

➕ NestJS와 Terminus

• Terminus는 NestJS 애플리케이션을 위한 통합 헬스 체크 모듈입니다. 데이터베이스, Redis, 마이크로서비스 등 다양한 의존성의 상태를 손쉽게 확인하고, 그 결과를 종합하여 응답하는 기능을 제공합니다.

• 사용법:

  1. 패키지 설치: npm install @nestjs/terminus
  2. 헬스 체크 컨트롤러 및 모듈 생성:
  3. HealthCheckService와 다양한 Health Indicator를 주입받아, 확인할 의존성들의 상태를 체크하는 로직을 작성합니다.

  // health.controller.ts
  import { Controller, Get } from '@nestjs/common';
  import { HealthCheck, HealthCheckService, TypeOrmHealthIndicator } from '@nestjs/terminus';
  
  @Controller('health')
  export class HealthController {
    constructor(
      private readonly health: HealthCheckService,
      private readonly db: TypeOrmHealthIndicator, // DB 상태 확인용 Indicator
    ) {}
  
    @Get()
    @HealthCheck() // 이 메서드가 헬스 체크 엔드포인트임을 선언
    check() {
      return this.health.check([
        // DB 연결이 살아있는지 확인
        () => this.db.pingCheck('database'),
        // 추가적으로 메모리, 디스크 공간 등을 확인할 수 있음
      ]);
    }
  }

• 결과: GET /health 요청 시, 모든 검사가 정상이면 200 OK와 함께 {"status":"ok", "info":{...}}를, 하나라도 실패하면 503 Service Unavailable과 함께 상세 오류를 반환합니다.

---

📌 요약

• Swagger (@nestjs/swagger)는 컨트롤러와 DTO 코드의 데코레이터를 기반으로 API 문서를 자동으로 생성하고 테스트 UI를 제공하여, 개발자 간의 협업 효율을 극대화하고 항상 최신 상태의 문서를 유지할 수 있게 합니다.
• 헬스 체크는 애플리케이션의 "건강 상태"를 외부 모니터링 시스템에 알리는 중요한 엔드포인트입니다.
• Terminus (@nestjs/terminus)는 데이터베이스 연결 상태 등 애플리케이션의 주요 의존성들이 정상적으로 동작하는지를 확인하는 헬스 체크 로직을 손쉽게 구현할 수 있도록 도와주는 모듈입니다.
• 헬스 체크를 통해 로드 밸런서나 Kubernetes가 장애를 자동으로 감지하고 복구하도록 만들어, 시스템의 가용성과 안정성을 크게 향상시킬 수 있습니다.