OpenAPI 기반 TypeScript API 클라이언트/코드 생성 도구 !!

백엔드 API와 프론트엔드가 커뮤니케이션할 때, 수동으로 타입·클라이언트 코드를 만드는 건 이제 너무 비효율이다.

그래서 등장한 것이 OpenAPI 스펙(OpenAPI/Swagger) 기반 코드 생성 도구다.
이런 도구들은 OpenAPI 스펙을 읽어서…

• 타입 정의 자동 생성
• fetch/axios 기반 API 호출 함수 생성
• React Query/SWR 훅 생성
• Mock 데이터/테스트 코드 생성

까지 해준다 !

즉 API 계약(contract)을 코드로 직결시키는 워크플로우를 만든다.

이번 글에서는 그런 도구 중에서 대표적이고 커뮤니티 논의도 활발한 3개를 골라서 정리했다.

 

1️⃣ Orval — “생산성 최우선 OpenAPI TS 생성기”

공식 --> https://orval.dev/
Github Stars / NPM 인기 -> 많은 샘플 + 광범위한 사용사례 확인됨

orval

 

❓ 뭐하는 라이브러리인가

OpenAPI v2/v3 스펙을 TypeScript 기반 API 클라이언트로 자동 변환한다.
기본적으로 타입 + HTTP 함수 + mock 코드까지 생성 가능

📌 왜 쓰면 좋은가

• 타입 안전  OpenAPI 스펙 그대로 TS 타입·함수 생성
• 풍부한 옵션  React Query / SWR / Angular HttpClient 등 다양하게 타겟 생성
• Mock/Stub 지원  MSW(mock service worker)까지 한 방에 생성 가능
• 자동화 가능  CI/CD나 코드 생성 스크립트에 자연스럽게 조합 가능

🧠 장점

• 코드 생성부터 훅까지 생산성 중심 설계
• 백엔드 준비 전 API 모킹으로 FE 먼저 개발 가능
• Config만 잘 짜면 “버그 없는” 클라이언트 코드 얻기 수월

👉 단점은 강력한 기능만큼 설정이 좀 복잡할 수 있다는 것 정도

 

2️⃣ OpenAPI TypeScript — “가볍게 타입·클라이언트 생성”

공식 ----> https://openapi-ts.dev/
장점 ! 빠른 타입 생성 + 타입 안전 API 호출 코드

OpenAPI TypeScript

 

❓ 뭐하는 라이브러리인가

OpenAPI 3.x 스펙을 빠르게 즉시 타입 + fetch 기반 클라이언트로 변환해준다.
별도의 무거운 설정 없이 가벼운 TypeScript 중심 생성이 특징이다.

📌 왜 쓰면 좋은가

• 설정 최소화  거의 설정 없이 바로 타입·API 생성
• 프레임워크 독립  React/Node/Next 등 어디든 가능
• Zero-runtime overhead  생성 코드는 순수 TS라 성능 & 번들 크기 부담 없음

🧠 장점

• 심플함 — CLI 한 방으로 스펙 → 타입
• 가벼운 타입 중심 — raw TS 타입 & API만 필요한 프로젝트에 최적

👉 다만 React Query/SWR 훅 생성 같은 추가 기능은 생태계 플러그인이나 따로결합 필요

 

3️⃣ Kubb — “플러그인 기반 확장성 높은 도구”

공식: https://kubb.dev/
철학: OpenAPI → TS로의 변환 뿐 아니라 다양한 플러그인으로 확장 가능한 에코시스템

Kubb: Generate SDKs for all your APIs

 

❓ 뭐하는 라이브러리인가

OpenAPI 스펙을 기반으로 타입·React Query/SWR/hooks·Zod validation·mock 등을 통합 생성하는 도구다.
기본 기능을 플러그인 형태로 구성해 필요한 컴포넌트만 골라 쓰는 구조가 특징

📌 왜 쓰면 좋은가

• 모듈화 & 확장성  플러그인 추가로 내가 원하는 코드만 생성
• TS + Zod + React Query 같은 조합을 하나의 워크플로우로
• mock/validation/테스트 코드 통합 가능

🧠 장점

• 확장성 — 기본 생성 외에 추가적인 워크플로우를 쉽게 연결
• 플러그인 에코시스템 — 커스텀 플러그인도 쉽게 작성 가능
• React 등 프레임워크 기능 다양 빌트인

👉 플러그인 방식이라 도입 초반 러닝커브는 있을 수 있지만, 팀 수준에서 일관된 API 소비 방식 구축 시 강력하다.

+ 그 외에도 ....

• openapi-typescript-codegen — 단순 TS/axios API 코드 생성 도구 (NPM)
• typed-openapi — 빠른 타입생성과 MAS 옵션 (GitHub)
• @openapi-generator-plus/typescript-fetch — OpenAPI Generator 템플릿 기반 TS Fetch client (NPM)
• Swagger Codegen / OpenAPI Generator 자체 생태계도 TS 코드 생성 옵션 존재 (openapi-generator.tech)

 

왜 이런 도구들을 쓰는가? 🎯

🚫 수동의 한계

수동으로 API 타입/클라이언트 작성하면…

• 업데이트 지연/실수 가능
• 명세와 코드 불일치
• 협업 생산성 감소

…같은 문제가 반복된다.

✅ 자동화의 장점

✅ 계약 기반 개발 (contract-first)
→ 백엔드가 먼저 OpenAPI 스펙을 만들고
FE는 그 스펙으로 클라이언트 코드 자동 생성

✅ 타입 안정성 극대화
→ TS inference가 워크플로우에 자연스럽게 녹아든다

✅ 백엔드 미완성 단계에서도 개발 가능
→ mock 데이터/훅을 먼저 만들어 빠르게 UI 개발