NestJS Swagger로 완벽한 API 문서를 만드는 5가지 베스트 프랙티스

NestJS는 엔터프라이즈급 백엔드 애플리케이션 구축에 최적화된 프레임워크입니다. 여기에 Swagger를 결합하면 자동화되고 일관된 API 문서를 손쉽게 만들 수 있죠. 단순히 문서가 "작동"하는 것을 넘어, "유지보수가 쉽고 명확한" API 문서를 만드는 5가지 핵심 베스트 프랙티스를 소개합니다.

---

1. DTO와 함께 @ApiProperty()를 의무화하세요

API 문서화의 핵심은 데이터 모델의 명세입니다. 요청(Request) 및 응답(Response)에 사용되는 DTO (Data Transfer Object) 클래스에 @ApiProperty() 데코레이터를 사용하여 필드의 상세 정보를 명시하는 것을 원칙으로 삼아야 합니다.

속성	역할	베스트 프랙티스
description	필드의 용도 설명	필수! 명확하고 간결하게 작성
example	예상되는 값	실제 데이터를 기반으로 제공 (테스트 용이성 확보)
required	필수 입력 여부	누락되지 않도록 명확하게 지정

🙅‍♀️ 나쁜 예: DTO에 @ApiProperty() 없이 필드만 나열. (문서가 불완전해짐)

🙆‍♂️ 좋은 예:

// CreatePostDto
@ApiProperty({ description: '게시글 제목', example: 'NestJS Swagger 문서화', required: true })
title: string;

---

728x90

2. NestJS Swagger CLI 플러그인으로 자동화하세요

반복적인 코드를 줄이고 개발 생산성을 높이는 핵심 전략입니다. NestJS의 Swagger 플러그인을 활성화하면, @ApiProperty()를 명시하지 않더라도 TypeScript의 타입 정보(Type)와 JSDoc/TSDoc 주석을 기반으로 많은 정보를 자동으로 유추하여 문서에 반영합니다.

• 설정 이점: DTO에 정의된 필드 타입 (예: string, number)이 Swagger 스키마 타입에 자동으로 매핑되어 수동 작업을 최소화할 수 있습니다.

---

3. @ApiResponse()로 모든 응답 케이스를 명시하세요

사용자(프런트엔드 개발자)가 API를 사용할 때 가장 중요한 정보 중 하나는 "어떤 응답을 기대해야 하는가" 입니다. 성공 응답(200, 201)뿐만 아니라, 오류 응답을 상세하게 문서화해야 합니다.

• 성공 (Success): @ApiResponse({ status: 200, description: '성공', type: PostDto })와 같이 응답 데이터 모델(DTO)을 명시합니다.
• 오류 (Error): 400 Bad Request, 401 Unauthorized, 404 Not Found 등 HTTP 상태 코드별로 예상되는 오류 형태(예: ErrorResponseDto)를 명시하여 프런트엔드가 에러 처리를 쉽게 할 수 있도록 돕습니다.

---

4. @ApiOperation()과 @ApiTags()로 탐색 편의성을 높이세요

문서가 많아질수록 탐색 편의성은 중요해집니다.

• @ApiTags('Users'): 관련된 엔드포인트를 하나의 그룹(폴더)으로 묶어 문서 좌측 패널을 깔끔하게 정리합니다.
• @ApiOperation():
  • summary: 엔드포인트의 목적을 한 문장으로 요약합니다. (예: "사용자 목록 조회")
  • description: 해당 API의 동작 방식, 특이사항, 제약 조건 등을 자세히 설명합니다. (예: "관리자만 접근 가능하며, 10개씩 페이징 처리됩니다.")

---

728x90

5. @ApiBearerAuth()로 보안 설정을 통합하세요

인증(Authentication)이 필요한 API라면, Swagger UI에서 바로 테스트할 수 있도록 보안 스키마를 설정해야 합니다.

1. DocumentBuilder에 addBearerAuth()를 설정하여 인증 방식을 정의합니다.
2. 각 컨트롤러 또는 특정 엔드포인트에 @ApiBearerAuth() 데코레이터를 추가하여 해당 API가 인증 토큰을 필요로 함을 명시합니다.

이를 통해 개발자는 Swagger UI의 "Authorize" 버튼을 이용해 JWT 토큰을 입력하고, 인증이 필요한 모든 API를 즉시 테스트할 수 있어 개발 워크플로우가 대폭 개선됩니다.

---

결론적으로, NestJS Swagger 문서화는 "코드가 문서이고, 문서가 테스트 도구"가 되도록 하는 데 집중해야 합니다. @ApiProperty()를 중심으로 DTO를 관리하고, 상세한 응답 명세를 제공하며, 자동화 도구와 보안 설정을 활용하면 유지보수와 협업이 극대화된 API 문서를 구축할 수 있습니다.