티스토리 뷰
<p>
프론트엔드 개발을 하다 보면 백엔드 API 스펙을 기반으로 타입을 만들고, axios 클라이언트를 작성하고, 때로는 react-query까지 붙이고 싶을 때가 있다.<br/>
이걸 손으로 하다 보면 중복 코드도 많고, 유지보수도 어렵다. 그래서 나온 게 OpenAPI 기반 코드 생성기들이다.
</p>
<p>
하지만 도구가 너무 많다. 어떤 건 타입만 되고, 어떤 건 Java 기반이고, 어떤 건 클라이언트는 만들지만 커스터마이징이 안 된다.<br/>
그래서 실전에서 자주 쓰이는 주요 도구들을 비교하고, 어떤 선택이 가장 실용적인지 정리했다.
</p>
<h3>📊 도구 기능 비교</h3>
<table border="1" cellspacing="0" cellpadding="6">
<thead>
<tr>
<th>도구</th>
<th>타입 생성</th>
<th>클래스 생성</th>
<th>클라이언트 생성</th>
<th>React Query</th>
<th>기반</th>
<th>비고</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>openapi-typescript</strong></td>
<td>O</td>
<td>X</td>
<td>X</td>
<td>X</td>
<td>Node.js</td>
<td>타입 전용. .d.ts만 생성</td>
</tr>
<tr>
<td><strong>swagger-typescript-api</strong></td>
<td>O</td>
<td>△ (템플릿 수정 시 가능)</td>
<td>O (axios/fetch)</td>
<td>X</td>
<td>Node.js + EJS</td>
<td>가장 유연. 클래스 구조 확장에 적합</td>
</tr>
<tr>
<td><strong>openapi-typescript-codegen</strong></td>
<td>O</td>
<td>X</td>
<td>O (axios/fetch)</td>
<td>X</td>
<td>Node.js</td>
<td>간단하고 빠르지만 구조 고정</td>
</tr>
<tr>
<td><strong>orval</strong></td>
<td>O</td>
<td>X</td>
<td>O (axios)</td>
<td>O</td>
<td>Node.js</td>
<td>react-query 통합 최적화, mock 지원</td>
</tr>
<tr>
<td><strong>openapi-generator</strong></td>
<td>O</td>
<td>O</td>
<td>O (다양한 언어)</td>
<td>X</td>
<td>Java CLI</td>
<td>공식 도구. 유연하지만 Java 기반</td>
</tr>
</tbody>
</table>
<h3>✔ 자동화 가능한 것</h3>
<ul>
<li><code>tags</code> → 클래스 단위 추론 (예: UserService)</li>
<li><code>operationId</code> → 메서드 이름으로 사용</li>
<li><code>parameters</code>, <code>requestBody</code>, <code>responses</code> → DTO 타입 생성</li>
</ul>
<pre><code>paths:
/users/{id}:
get:
tags: [UserService]
operationId: getUser
</code></pre>
<h3>❌ 자동화 한계 (OpenAPI 자체의 한계)</h3>
<ul>
<li>서비스 계층 구조 표현 불가</li>
<li>내부 호출 흐름 추론 불가 (ex. 내부적으로 validateAuth 호출)</li>
<li>의도 기반 메시지 정의 불가 (gRPC처럼 목적 명확화 불가)</li>
<li>스트리밍, 상태 유지 표현 불가</li>
</ul>
<h3>🛠 실전 확장 전략</h3>
<ol>
<li><strong>swagger-typescript-api</strong>로 타입/클라이언트 생성</li>
<li><strong>ts-morph</strong>로 interface → class 자동 변환</li>
<li><code>fromJSON()</code>, <code>toJSON()</code>, <code>clone()</code>, <code>fromPartial()</code> 등의 유틸 삽입</li>
<li><code>class-validator</code> 자동 데코레이터 삽입</li>
</ol>
<pre><code class="ts">class User {
constructor(public id: string, public profile: Profile) {}
static fromJSON(data: any): User {
return new User(data.id, Profile.fromJSON(data.profile));
}
}
</code></pre>
<h3>📈 다운로드 트렌드 (2025년 기준)</h3>
<ul>
<li><strong>openapi-typescript</strong> – 약 1.3M (타입만 추출 목적)</li>
<li><strong>openapi-typescript-codegen</strong> – 약 300K</li>
<li><strong>swagger-typescript-api</strong> – 약 250K</li>
<li><strong>orval</strong> – 약 100K</li>
<li><strong>openapi-generator</strong> – npm 사용 거의 없음 (Java CLI 기반)</li>
</ul>
<h3>🎯 목적별 추천 도구</h3>
<table border="1" cellspacing="0" cellpadding="6">
<thead>
<tr>
<th>목적</th>
<th>추천 도구</th>
</tr>
</thead>
<tbody>
<tr>
<td>가장 유연하고 확장 가능한 구조</td>
<td><strong>swagger-typescript-api</strong></td>
</tr>
<tr>
<td>빠르게 axios 클라이언트만 쓰고 싶을 때</td>
<td>openapi-typescript-codegen</td>
</tr>
<tr>
<td>타입 정의만 필요할 때</td>
<td>openapi-typescript</td>
</tr>
<tr>
<td>React Query 자동 통합이 중요한 경우</td>
<td>orval</td>
</tr>
<tr>
<td>클래스 + 클라이언트 완전체가 필요한 경우 (CLI 기반)</td>
<td>openapi-generator</td>
</tr>
</tbody>
</table>
<h3>✅ 결론</h3>
<p>
단순 타입 생성이 아니라, 서버 모델을 클라이언트 model로 서 사용하는 것 까지 고려한다면<br/>
<strong>swagger-typescript-api</strong>가 가장 나에게 맞는 구조인 것 같다.<br/>
템플릿 수정, 구조 분할, 후처리 자동화까지 가능해서 팀 단위로 도입하기에 매우 적합하다.
</p>
<p>
React 기반 프로젝트에서 클라이언트 + react-query 자동화를 원한다면 <strong>orval</strong>도 좋은 대안이다.<br/>