OpenAPI → TypeScript 자동화: 어떤 도구를 선택해야할까?

프론트엔드 개발을 하다 보면 백엔드 API 스펙을 기반으로 타입을 만들고, axios 클라이언트를 작성하고, 때로는 react-query까지 붙이고 싶을 때가 있다.
이걸 손으로 하다 보면 중복 코드도 많고, 유지보수도 어렵다. 그래서 나온 게 OpenAPI 기반 코드 생성기들이다.

하지만 도구가 너무 많다. 어떤 건 타입만 되고, 어떤 건 Java 기반이고, 어떤 건 클라이언트는 만들지만 커스터마이징이 안 된다.
그래서 실전에서 자주 쓰이는 주요 도구들을 비교하고, 어떤 선택이 가장 실용적인지 정리했다.

📊 도구 기능 비교

도구	타입 생성	클래스 생성	클라이언트 생성	React Query	기반	비고
openapi-typescript	O	X	X	X	Node.js	타입 전용. .d.ts만 생성
swagger-typescript-api	O	△ (템플릿 수정 시 가능)	O (axios/fetch)	X	Node.js + EJS	가장 유연. 클래스 구조 확장에 적합
openapi-typescript-codegen	O	X	O (axios/fetch)	X	Node.js	간단하고 빠르지만 구조 고정
orval	O	X	O (axios)	O	Node.js	react-query 통합 최적화, mock 지원
openapi-generator	O	O	O (다양한 언어)	X	Java CLI	공식 도구. 유연하지만 Java 기반

✔ 자동화 가능한 것

• tags → 클래스 단위 추론 (예: UserService)
• operationId → 메서드 이름으로 사용
• parameters, requestBody, responses → DTO 타입 생성

paths:
/users/{id}:
  get:
    tags: [UserService]
    operationId: getUser

❌ 자동화 한계 (OpenAPI 자체의 한계)

• 서비스 계층 구조 표현 불가
• 내부 호출 흐름 추론 불가 (ex. 내부적으로 validateAuth 호출)
• 의도 기반 메시지 정의 불가 (gRPC처럼 목적 명확화 불가)
• 스트리밍, 상태 유지 표현 불가

🛠 실전 확장 전략

1. swagger-typescript-api로 타입/클라이언트 생성
2. ts-morph로 interface → class 자동 변환
3. fromJSON(), toJSON(), clone(), fromPartial() 등의 유틸 삽입
4. class-validator 자동 데코레이터 삽입

class User {
  constructor(public id: string, public profile: Profile) {}

  static fromJSON(data: any): User {
    return new User(data.id, Profile.fromJSON(data.profile));
  }
}

📈 다운로드 트렌드 (2025년 기준)

• openapi-typescript – 약 1.3M (타입만 추출 목적)
• openapi-typescript-codegen – 약 300K
• swagger-typescript-api – 약 250K
• orval – 약 100K
• openapi-generator – npm 사용 거의 없음 (Java CLI 기반)

🎯 목적별 추천 도구

목적	추천 도구
가장 유연하고 확장 가능한 구조	swagger-typescript-api
빠르게 axios 클라이언트만 쓰고 싶을 때	openapi-typescript-codegen
타입 정의만 필요할 때	openapi-typescript
React Query 자동 통합이 중요한 경우	orval
클래스 + 클라이언트 완전체가 필요한 경우 (CLI 기반)	openapi-generator

✅ 결론

단순 타입 생성이 아니라, 서버 모델을 클라이언트 model로 서 사용하는 것 까지 고려한다면
swagger-typescript-api가 가장 나에게 맞는 구조인 것 같다.
템플릿 수정, 구조 분할, 후처리 자동화까지 가능해서 팀 단위로 도입하기에 매우 적합하다.

React 기반 프로젝트에서 클라이언트 + react-query 자동화를 원한다면 orval도 좋은 대안이다.