[DX 개선] Orval을 활용한 API Boilerplate 자동화 경험기

기획은 계속 바뀌는데 개발 일정은 고정되어 있었다

서비스 전체 개편을 진행하게 되면서 짧은 기간 안에 매우 많은 화면을 개발해야 하는 상황이 있었습니다.

페이지, 슬라이드아웃, 모달을 포함해 30개 이상의 화면이 새롭게 추가되어야 했고, 문제는 단순히 화면 수만 많았던 것이 아니었습니다.

기획은 완전히 확정되지 않은 상태였고, 개발을 진행하는 동안에도 계속해서 요구사항이 변경되고 있었습니다.
하지만 릴리즈 일정은 고정되어 있었고, 결국 개발자가 실제 구현에 사용할 수 있는 시간은 계속 줄어드는 구조였습니다.

이런 상황에서 저는 자연스럽게 다음 질문을 하게 되었습니다.

“지금 내가 정말 제품 개발에 시간을 쓰고 있는 걸까? 의미 없는 반복 작업에 시간을 쏟는거 아닐까?” 

 

---

반복되는 API Boilerplate 문제

기존 구조에서는 새로운 API가 추가될 때마다 반복적으로 작성해야 하는 코드가 많았습니다.

예를 들면 다음과 같은 구조입니다.

API 통신 계층

import axios from '@/lib/axios';

export const fetchProducts = async (categoryId: string) => {
  try {
    const { data } = await axios.get(
      `/api/categories/${categoryId}/products`
    );

    return data;
  } catch (error) {
    console.error('Failed to fetch products', error);
    throw error;
  }
};

React Query 계층

import { useQuery } from '@tanstack/react-query';
import { fetchProducts } from './fetchProducts';

export const useProducts = (categoryId: string) => {
  return useQuery({
    queryKey: ['products', categoryId],
    queryFn: () => fetchProducts(categoryId),
    enabled: !!categoryId,
  });
};

당시 작성하던 대부분의 API 코드들은 다음 요소만 달랐습니다.

• endpoint
• request/response type
• queryKey
• mutation/query 여부

하지만 전체 구조는 거의 동일했습니다.

결국 저는 기능 개발보다 반복적인 boilerplate 생산에 많은 시간을 쓰고 있다는 것을 인식하게 되었습니다.

평소에는 크게 체감되지 않았지만, 서비스 전체 개편처럼 API 연동이 폭발적으로 증가하는 시점에서는 이 반복 작업이 일정 자체를 위협하는 수준의 비용이 되었습니다.

---

처음에는 AI로 해결하려고 했다

처음에는 Cursor, Claude 같은 AI 기반 코드 생성 방식을 고민했습니다.

예를 들어:

• 팀 내부 규칙 정의
• rules.md 작성
• API 생성 규칙 문서화
• 프롬프트 기반 생성

같은 방식입니다.

하지만 고민하다 보니 한 가지 생각이 들었습니다.

“이 문제를 정말 AI로 해결해야 하는 걸까?”

 

 

이미 제 팀에는 OpenAPI 기반 Swagger 명세가 존재하고 있었습니다.
그렇다면 사람이 프롬프트를 통해 반복 생성하도록 만드는 것보다, OpenAPI 스펙 자체를 활용하는 것이 더 구조적이지 않을까 생각했습니다. 그렇게 발견한 도구가 바로 Orval이었습니다.

---

Orval을 선택한 이유

우리 팀은 백엔드가 이미 OpenAPI 기반으로 API를 개발하고 있었습니다.

즉, 새로운 프로세스를 강요하는 것이 아니라 이미 존재하는 명세를 활용할 수 있는 상황이었습니다.

Orval은 OpenAPI 스펙을 기반으로 다음을 자동 생성할 수 있었습니다.

• axios 기반 API 함수
• react-query hook
• TypeScript 타입
• MSW mock 데이터

즉, 기존에 반복적으로 작성하던 boilerplate 대부분을 자동화할 수 있었습니다.

---

하지만 전체 적용은 하지 않았다

중요했던 건 “어떻게 도입할 것인가”였습니다.

이미 서비스에는 기존 API 구조가 매우 많이 존재하고 있었고, 전체를 한 번에 변경하는 것은 영향도가 너무 컸습니다.

 

그래서 백엔드 개발자와 논의 후 신규로 추가되는 API에 대해서만 선별적으로 적용 하기로 결정했습니다.

이 결정은 결과적으로 매우 중요했습니다.

 

왜냐하면:

• 기존 코드 영향 최소화
• 점진적 도입 가능
• 팀 적응 비용 감소
• 리스크 관리 가능

이라는 장점이 있었기 때문입니다.

실무에서는 “좋은 기술”보다 “안전하게 도입 가능한 기술”이 더 중요하다고 생각합니다.

---

실제 적용 방식

우리는 tags-split 모드를 활용해 OpenAPI tag 기준으로 코드를 분리했습니다.

export default defineConfig({
  ecommerceApi: {
    input: {
      target: 'http://localhost:8080/v3/api-docs',
    },
    output: {
      mode: 'tags-split',
      target: 'src/api/generated',
      client: 'react-query',
      mock: true,
    },
  },
});

 

 

config를 설정 후 다음 명령어를 입력합니다.

yarn generate:api

 

위의 script 한 번으로 다음과 같은 구조가 자동 생성되었습니다.

src/api/generated/
├── product/
├── category/
├── user/
├── order/
└── ...

 

 

실제로는 다음과 같은 것들까지 모두 생성되었습니다.

• axios 함수
• react-query hook
• schema type
• msw mock

 

---

결과 — API 연동 시간이 극적으로 감소했다

도입 이후 가장 크게 체감한 것은 “이제 API 연동 자체에 시간을 거의 쓰지 않게 되었다”는 점이었습니다.

 

AS-IS

기존에는 새로운 API 하나가 추가될 때마다 다음과 같은 액션을 반복했습니다.

• axios 함수 작성
• 타입 정의
• react-query hook 작성
• queryKey 관리
• mutation/query 분리

등을 직접 구현해야 했습니다.

 

 

TO-BE

하지만 Orval 도입 이후에는 다음 액션으로 대부분이 해결되었습니다.

• OpenAPI 정의
• generate 실행

 

 

 

실제로 서비스 전체 개편 기간 동안 기존 대비 API 연동에 사용하던 시간의 10%도 안 되는 수준으로 개발 시간을 줄일 수 있었습니다.

그 덕분에 아래와 같은 “제품 자체의 문제”에 더 많은 시간을 사용할 수 있었습니다.

• 촉박한 일정 대응
• 기획 변경 대응
• UI/UX 개선 집중

 

---

그런데 자동화에도 문제가 있었다

하지만 사용하면서 또 다른 문제가 발생했습니다.

우리는 tags-split 모드를 사용하고 있었기 때문에 OpenAPI의 tag 이름 기준으로 generated 파일 경로가 생성되었습니다.

 

 

예를 들면 다음 구조입니다.

import { useProducts } from '@/api/generated/product/product';

 

 

 

문제는 백엔드에서 tag 이름을 변경하면 generated 경로 자체가 바뀌어버린다는 점이었습니다.

결국 프로젝트 전반에서 import 경로가 대량으로 깨지는 문제가 발생했습니다.

 

즉, 자동 생성 코드와 서비스 코드가 너무 강하게 결합(coupling)되어 있었던 것입니다.

---

해결 — Generated Layer를 직접 참조하지 않도록 만들었다

이 문제를 해결하기 위해 구조를 다시 정리했습니다.

핵심 아이디어는 서비스 코드가 generated 구조를 직접 알지 못하게 만드는 것이었습니다.

 

 

저는 중간 layer를 추가했습니다.

src/api/hooks/*

 

// product.ts
export * from '../generated/product/product';

 위의 예시 코드처럼 barrel 파일만 두었습니다.

 

 

그리고 서비스 코드에서는 다음과 같이 사용 가능하도록 변경하였습니다.

import { useProducts } from '@/api/hooks/product';

 

 

 

 

---

이 구조가 중요했던 이유

이후부터는 백엔드에서 tag 이름이 변경되더라도

• generated 경로만 수정
• barrel export만 수정

하면 되었고, 실제 서비스 코드 수정은 거의 발생하지 않게 되었습니다.

 

 

결국 이 구조는

• generated layer
• service layer

사이에 완충 지점을 만든 셈이었습니다.

 

 

자동화 자체보다 “자동화 결과물을 어떻게 격리할 것인가”가 더 중요하다는 것을 경험하게 된 순간이었습니다.

 

 

---

마무리

이번 경험을 통해 느낀 점은 단순히 “Orval이 편하다”가 아니었습니다.

정말 중요했던 것은 다음과 같은 이점이었습니다.

• 반복 작업 제거
• 개발자 집중도 향상
• 일정 대응 능력 확보
• 변경 대응 비용 감소

 

특히 서비스 전체 개편처럼 요구사항이 계속 바뀌고, API가 급증하며 일정은 고정된 상황에서는 DX 개선이 단순한 편의성이 아니라 생산성과 일정 안정성을 직접적으로 좌우한다고 느꼈습니다.

 

그리고 또 하나 느낀 점은 자동화는 생성 자체보다 coupling 관리가 더 중요하다는 점이었습니다.

 

반복 작업을 줄이는 것만으로 끝나는 것이 아니라,
그 자동화 결과물이 서비스 구조를 침범하지 않도록 설계하는 것까지 포함되어야 진짜 DX 개선이라고 생각합니다.