서버리스 환경에서 Swagger DTO 표시 문제 해결 및 사용 패턴 개선하기

들어가며

안녕하세요. 노머스 백엔드 엔지니어 임승훈입니다.

이번 글에서는 서버리스 마이크로서비스 환경에서 Swagger를 통해 API 문서를 관리하며 겪었던 이슈와 해결 과정을 공유하고자 합니다. 번들링 환경에서 DTO 클래스명이 의도한 대로 표시되지 않는 문제를 발견했고, 이를 계기로 Swagger 사용 패턴 전반을 점검하고 개선할 수 있었습니다.

개선의 계기

이전에 👉 Serverless 마이크로서비스 환경에서 API Docs 통합하기에서 소개해드린 것처럼 노머스에서는 Swagger UI를 사용해 API Docs를 구성하고 있습니다.

서버리스 환경에서 번들링을 거쳐 배포하는 과정에서 Swagger UI가 잘 작동하는 것처럼 보였지만, 프론트엔드 팀과 OpenAPI 스펙을 공유하여 타입을 자동 생성하는 테스트를 진행하던 중 예상치 못한 문제를 발견했습니다. 배포 후 Swagger 문서에서 DTO 클래스명이 우리가 정의한 이름대로 표시되지 않는 것이었습니다.

발견한 문제점들

Swagger 문서를 자세히 점검하며 발견한 문제점은 크게 네 가지였습니다.

1. 번들링 시 클래스명 표시 이슈

배포 후 Swagger UI를 확인하니, 우리가 정의한 DTO 클래스명이 의도한 대로 표시되지 않았습니다.

배포 환경의 Swagger UI에서 다음과 같은 현상들이 발견되었습니다:

• CreateOrderDto가 CreateOrderDto1, _CreateOrderDto 등 의도하지 않은 문자가 붙어서 표시
• GetProductQuery가 Object 또는 의미 없는 이름으로 표시
• 같은 DTO가 여러 번 정의되어 Swagger 문서가 복잡해짐

당시 Swagger 문서를 OpenAPI 스펙으로 export하여 프론트엔드 팀과 타입을 공유하기 위한 준비를 하고 있었습니다. 위 이미지처럼 [object Object] 같은 타입이 생성되면 프론트엔드에서 TypeScript 타입을 자동 생성할 때 실제 컴파일 오류가 발생합니다. DTO 이름이 CreateOrderDto1, Object 같은 형태로 생성되면 코드에서 활용하기 어렵기 때문에, 백엔드와 프론트엔드 간 타입 공유라는 목표를 달성하기 위해서는 반드시 해결이 필요했습니다.

원인:

이러한 현상은 esbuild 등 번들러가 코드를 최적화하는 과정에서 클래스의 메타데이터가 손실되거나 변경되기 때문에 발생합니다. Swagger는 런타임에 클래스 이름을 읽어서 문서에 표시하는데, 번들링 후에는 클래스 정보가 제대로 전달되지 않아 Swagger가 중복을 피하기 위해 자동으로 숫자를 붙이게 됩니다.

// 우리가 작성한 코드
export class CreateOrderDto {
  // ...
}

export class GetGoodsOptionsResponse {
  // ...
}

// Swagger에서 표시되는 이름
CreateOrderDto1  // 의도하지 않은 이름
_GetGoodsOptionsResponse  // 언더스코어가 붙거나
Object  // 아예 의미 없는 이름으로 변경

// 프론트엔드에서 자동 생성된 타입
interface CreateOrderDto1 {  // 이런 타입은 활용하기 어려움
  // ...
}

interface _GetGoodsOptionsResponse {  // 예상치 못한 네이밍
  // ...
}

2. Controller와 DTO 간 데코레이터 관리

서비스 초기에는 Swagger 사용 패턴에 따라 @ApiQuery, @ApiParam, @ApiHeader 등의 데코레이터를 Controller에 직접 선언하고 있었습니다. 하지만 서비스가 성장하면서 DTO 중심으로 API 스펙을 관리하는 것이 더 효율적이라는 것을 알게 되었습니다. 초기의 접근 방식을 그대로 유지하면서 새로운 코드가 추가되다 보니 다음과 같은 문제가 있었습니다:

• 같은 정보를 Controller와 DTO 양쪽에서 관리
• DTO 변경 시 Controller 데코레이터도 함께 수정해야 하는 번거로움
• 미사용 속성들이 계속 남아있어 문서를 더 명확하게 만들 필요

3. 타입 표기 방식 통일

서비스 초기에는 Swagger 문서화에 대한 명확한 가이드가 없었고, 각자의 방식으로 작성하다 보니 다양한 작성 패턴이 공존하게 되었습니다. 시간이 지나며 권장되는 작성 방식이 발전했지만 기존 코드는 업데이트되지 않아 통일이 필요했습니다:

• type: Number vs type: 'number' 등 타입 지정 방식의 차이
• empty array를 기본값이나 예제로 사용한 케이스 존재
• 설명(description)을 추가하면 더 명확해질 DTO 필드들
• Header의 언어 필드 등 공통 타입의 서비스별 통일 필요

4. Union 타입 응답 처리

코드베이스를 점검하던 중, 일부 API의 응답 타입이 Union 타입으로 정의되어 있는 것을 발견했습니다. Swagger의 oneOf 스펙은 여러 응답 타입 중 하나를 반환할 수 있음을 표현하지만, 실제로 OpenAPI 스펙에서 타입을 생성할 때는 하나의 타입으로만 추론되는 경우가 있어 프론트엔드에서 정확한 타입 정보를 받기 어려울 수 있습니다.

총 3개 메서드가 응답 자체가 oneOf/Union 타입으로 정의되어 있었습니다. 이 문제의 해결 방법은 아래 6. 공통 Response 래퍼 타입 처리 개선에서 다룹니다.

개선 방법

발견한 문제들을 해결하기 위해 다음과 같은 작업을 진행했습니다.

1. @ApiSchema 데코레이터로 클래스명 명시적 지정

모든 DTO 클래스에 @ApiSchema() 데코레이터를 추가하고, 클래스명을 명시적으로 지정하여 번들링 후에도 올바른 이름이 유지되도록 했습니다.

@ApiSchema({ name: 'CreateOrderDto' })
export class CreateOrderDto {
  @ApiProperty({ type: 'string', description: '수령인 이름' })
  recipientName: string;
}

이렇게 하면 번들링 과정에서 클래스명이 변경되더라도 Swagger는 우리가 지정한 'CreateOrderDto' 이름을 사용하여 문서에 표시합니다. 더 이상 CreateOrderDto1, CreateOrderDto2나 Object 같은 의미 없는 이름이 나타나지 않습니다.

이 작업을 진행하면서 Swagger는 같은 이름의 DTO가 여러 개 존재할 경우 하나만 처리한다는 점을 유의했습니다. 마이크로서비스 환경에서는 서비스 간 DTO 이름이 중복되지 않도록 네이밍 규칙을 정하면서 작업했습니다.

2. Controller 데코레이터를 DTO로 이전

기존에 Controller에 흩어져 있던 @ApiQuery, @ApiParam, @ApiHeader를 DTO로 통합했습니다.

변경 전:

@Get()
@ApiHeader({ name: 'lang' })
@ApiQuery({ name: 'productId', type: 'number' })
async getProduct(@Headers('lang') lang: string, @Query('productId') id: number) {
  // ...
}

변경 후:

@Get()
async getProduct(@Headers() headers: GetProductHeaders, @Query() query: GetProductQuery) {
  // ...
}

Controller가 간결해지고, DTO만 보면 API 스펙을 한눈에 파악할 수 있게 되었습니다.

3. 타입을 문자열 리터럴로 통일

번들링 환경에서 안정적으로 동작하도록 타입을 문자열 리터럴로 통일했습니다.

// 변경 전
@ApiProperty({ type: Number })
price: number;

// 변경 후
@ApiProperty({ type: 'number' })
price: number;

// 배열인 경우
@ApiProperty({ type: 'number', isArray: true })
discountRates: number[];

4. nullable과 optional 처리 명확화

// Optional 필드
@ApiPropertyOptional({ type: 'string' })
@IsOptional()
memo?: string;

// Nullable 필드
@ApiProperty({ type: 'string', nullable: true })
couponCode: string | null;

5. 공통 타입 통일

모든 서비스에서 사용하는 header 타입을 통일하여 일관성을 확보했습니다.

// 공통 타입 정의
export const ALL_LANGUAGES = ['ko', 'en', 'ja', 'zh'] as const;
export type Language = typeof ALL_LANGUAGES[number];

// 모든 서비스에서 동일하게 사용
@ApiSchema()
export class CommonRequestHeader {
  @ApiProperty({ enum: ALL_LANGUAGES })
  lang: Language;
}

6. 공통 Response 래퍼 타입 처리 개선

노머스에서는 모든 API 응답을 일관된 형태로 제공하기 위해 FrommResponse<T> 공통 Response 래퍼를 사용하고 있습니다. 하지만 Swagger 문서 생성 시 다음과 같은 문제가 있었습니다:

기존 문제:

• FrommResponse.data가 void인 경우에도 Swagger에 빈 객체로 표시됨
• FrommResponse.data가 null일 수 있는 경우 required: false 설정이 어려움
• FrommResponse<T>에서 T가 Union 타입인 경우 Swagger의 oneOf, allOf 등 복합 타입 처리 제약

위 이미지처럼 응답의 data 필드가 Union 타입(oneOf)으로 여러 가능한 타입을 가지는 경우, OpenAPI 스펙에서 타입을 정확하게 표현하는 것이 중요합니다.

개선 방법:

FrommResponse 클래스의 data 필드 처리를 개선했습니다.

• void 처리: data가 void인 경우 Swagger 상에서 표시되지 않도록 수정
• nullable 처리: data가 nullable인 경우 required: false로 설정 가능하도록 수정
• 복합 타입 처리: data가 Union 타입인 경우 oneOf, allOf 등의 OpenAPI 스펙을 올바르게 생성하도록 개선

이를 통해 각 API의 응답 타입에 맞는 정확한 Swagger 문서가 생성되고, 올바른 타입을 알 수 있게 되었습니다.

결과 및 개선사항

배포 후 정상 작동 확인

• DTO 클래스명이 의도한 대로 Swagger UI에 올바르게 표시
• OpenAPI 스펙에서 생성된 TypeScript 타입이 정확한 이름으로 생성되어 프론트엔드 팀과의 타입 공유 성공
• Request/Response 스키마가 명확하게 렌더링
• 모든 마이크로서비스의 Swagger 문서가 일관성 있게 개선

개발 경험 개선

• Controller 코드가 간결해져 가독성 향상
• DTO만 보면 API 스펙을 한눈에 파악 가능
• 공통 타입 재사용으로 코드 중복 감소
• 명시적 타입 정의로 IDE 자동완성 품질 향상

유지보수성 향상

• DTO 변경 시 Swagger 문서 자동 업데이트 보장
• 새로운 API 추가 시 동일한 패턴으로 빠르게 작성 가능
• 타입 안정성 강화로 런타임 에러 감소

마치며

처음에는 프론트엔드와 타입을 공유하기 위한 준비 과정에서 우연히 발견한 문제였지만, 이를 해결하는 과정에서 Swagger 사용 패턴 전반을 점검하며 더 나은 방향으로 발전시킬 수 있었습니다. 특히 UI상으로는 속성 등이 올바르게 보여서 처음에는 알아차리기 어려웠기 때문에, 프론트엔드 팀과의 협업이 없었다면 계속 놓치고 있었을 문제였습니다.

이번 작업을 통해 배운 점은 다음과 같습니다:

1. 번들링 환경의 특성 이해: 번들러는 코드를 최적화하면서 클래스 메타데이터를 변경할 수 있습니다. 배포 환경에서만 발생하는 이슈들은 발견하기 어려우므로, 명시적인 메타데이터 지정이 중요합니다.
2. 일관된 타입 정의 패턴: 마이크로서비스 환경에서는 모든 서비스가 동일한 패턴을 따를 때 전체 서비스의 품질을 효과적으로 높일 수 있습니다.
3. DTO 중심의 API 문서화: Controller에 흩어진 메타데이터를 DTO로 통합하면, API 스펙을 한눈에 파악할 수 있고 유지보수성이 크게 향상됩니다.
4. 팀 간 협업의 중요성: 프론트엔드 팀과의 타입 공유 작업이 없었다면 발견하지 못했을 문제였습니다. 서로 다른 관점에서 바라보는 것이 품질 향상에 도움이 됩니다.

서버리스 환경에서 Swagger를 사용하며 비슷한 고민을 하시는 분들께 이 글이 도움이 되었으면 좋겠습니다.

읽어주셔서 감사합니다.