개요

@nestjs/swagger는 NestJS와 Swagger(OpenAPI) 스펙을 연결해 API 문서를 자동 생성하는 모듈임 DTO(Data Transfer Object) 클래스에 메타데이터를 부여해 타입과 예시, 설명 등을 Swagger UI에 노출하는 흐름으로 작동함 핵심 도구는 @ApiProperty와 DTO 유틸리티 타입들(PickType, OmitType, PartialType)임

ApiProperty 개념과 사용

@ApiProperty는 DTO 속성 단위로 문서화 메타데이터를 부여하는 데코레이터임 타입, 설명, 예시, 필수 여부 등을 정의해 Swagger UI에 명확한 스키마 제공 코드와 문서가 한 소스에서 유지되어 일관성 확보에 유리함

간단 사용 예시

class CreateUserDto {
  @ApiProperty({ description: "사용자 이름", example: "John Doe" })
  name: string;
}

이 속성 정의만으로 Swagger 스키마에 name 필드의 설명과 예시가 노출됨

주요 옵션

필요한 만큼만 설정해 최소 문서화로 시작하고 점진적으로 보강하는 방식 권장

  • description: 속성 의미 설명
  • example: 대표 예시 값
  • required: 필수 여부, 기본값 true
  • type: 복잡 타입 또는 명시가 필요한 경우 사용
  • enum: 허용 값 집합 지정
  • isArray: 배열 여부 명시

옵션 스니펫

@ApiProperty({ description: '사용자 나이', example: 30, type: Number })
age: number

@ApiProperty({ enum: ['admin', 'user'] })
role: string

@ApiProperty({ type: String, isArray: true })
tags: string[]

required는 별도 지정 없으면 true로 처리됨 PartialType을 통해 생성된 DTO에서는 해당 필드들이 선택적이 되어 Swagger에도 반영됨

배열과 중첩 객체

배열 표시

@ApiProperty({ type: String, isArray: true, description: '태그 목록' })
tags: string[]

중첩 객체 표시

class AddressDto {
  @ApiProperty()
  street: string;

  @ApiProperty()
  city: string;
}

class CreateUserDto {
  @ApiProperty({ type: AddressDto })
  address: AddressDto;
}

Swagger UI에서는 정의한 타입을 따라 객체 구조와 예시가 노출됨

PickType 개념과 사용

PickType은 기존 DTO에서 특정 속성만 선택해 새로운 DTO 생성하는 유틸리티임 중복 정의 없이 필요한 필드만 가져와 입력이나 응답 모델을 재사용 가능 Swagger 스키마도 선택된 필드만 반영됨

기본 사용 예시

class CreateUserDto {
  username: string;
  password: string;
  email: string;
}

class LoginDto extends PickType(CreateUserDto, ["username", "password"]) {}

활용 포인트

  • 코드 재사용성 향상 및 중복 제거
  • 입력 모델과 응답 모델을 상황에 맞춰 최소 단위로 분리 가능
  • 스키마가 원본 DTO 변경을 자동 추적해 일관성 유지

관련 유틸리티

  • OmitType: 특정 속성만 제외하고 나머지로 새 DTO 생성
class PublicUserDto extends OmitType(CreateUserDto, ["password"]) {}
  • PartialType: 모든 속성을 선택적으로 변경해 부분 업데이트 시 유용
class UpdateUserDto extends PartialType(CreateUserDto) {}

조합 사용 시 공통 DTO 하나를 기준으로 입력, 응답, 수정 등 다양한 변형 모델을 일관되게 관리 가능

팁

  • 타입 추론에 의존해 단순 필드는 최소 정의, 설명과 예시가 필요한 필드에만 @ApiProperty 부여
  • 복잡 타입이나 배열, enum은 type, isArray, enum으로 명시적 선언 권장
  • 응답 모델에서 노출되면 안 되는 필드는 OmitType으로 사전에 제거
  • 부분 업데이트 API는 PartialType 기반 DTO로 required 플래그 자동 조정 유도
  • 문서 신뢰성을 위해 예시 값 example은 실제 도메인 형식과 일치하도록 유지

마무리

@ApiProperty로 DTO 속성 단위 문서화를 정교하게 관리하고, PickType OmitType PartialType으로 DTO 재사용성을 극대화하는 전략 권장 코드와 문서의 단일 소스화를 통해 API 스펙의 정확성, 추적 가능성, 유지보수성을 동시에 확보 가능

참고자료