이 시리즈의 첫 글에서 “코드를 쓰기 전에 OpenAPI 계약부터 합의하자"는 이야기를 했습니다. 이번 글은 그 계약이 실제로 본전을 뽑게 해주는 도구에 대한 이야기입니다.

프론트엔드의 API 계층을 손으로 짜는 건, 즐겁다고 말하는 사람을 본 적이 없는 종류의 일입니다. 백엔드 문서에서 타입을 베껴 적고, 마흔 번째 똑같은 요청 래퍼를 쓰고, 3주 뒤에 누군가 필드명을 바꾸면 호출의 절반이 조용히 깨지죠. Orval은 이 일 자체를 없애줍니다. OpenAPI 스펙을 가리키기만 하면 클라이언트 코드를 생성해줍니다. 모든 엔드포인트에 대한 타입이 잡힌 함수, 계약과 정확히 일치하는 모델, 그리고 백엔드가 존재하기도 전에 개발에 쓸 수 있는 목(mock)까지.

프론트엔드 팀이 좋아하는 이유

#

목 생성이 은근히 저평가된 부분입니다. 스펙만 합의되면 프론트엔드는 가짜 서버를 띄워놓고 UI 전체를 거기에 대고 만들 수 있습니다. 영원히 “거의 다 됐어요” 상태인 엔드포인트를 기다릴 필요가 없죠. 진짜 백엔드가 나오면 클라이언트의 방향만 돌려주면 대부분 그대로 동작합니다. 양쪽이 같은 문서에서 만들어졌으니까요.

또 하나의 수확은, 지루한 코드가 구조적으로 올바르게 나온다는 점입니다. 손으로 짠 요청 바디에서 필드명을 잘못 치는 사람이 없어집니다. 애초에 손으로 요청 바디를 짜는 사람이 없어졌으니까요.

백엔드 팀도 좋아하는 이유

#

스펙이 단일 진실 공급원이 되면 일상적인 대화가 달라집니다. “이 엔드포인트가 뭘 반환하더라?“라는 채팅 스레드 대신, 프론트엔드는 생성된 타입을 읽으면 됩니다. 백엔드 개발자는 덜 끊기고, 피드백은 더 빨리 받습니다. 프론트엔드가 목을 상대로 만들어보다가 API가 어딘가 어색하다고 느끼면, 그걸 알게 되는 시점이 프로덕션 이후가 아니라 아직 고치기 싼 시점입니다.

우리 워크플로에 녹이는 방법

#

별다른 건 없습니다. 백엔드가 스펙을 제안하고, 양 팀이 리뷰하고, 프론트엔드는 Orval로 클라이언트와 목을 생성해 개발을 시작하고, 백엔드는 같은 계약에 맞춰 실제 엔드포인트를 구현합니다. 스펙이 바뀌면 양쪽에서 다시 생성하고, 뭐가 깨졌는지는 컴파일러가 정확히 알려줍니다. 사실 이 마지막 부분이 핵심입니다. 프론트와 백엔드 사이의 어긋남이 프로덕션 버그가 아니라 컴파일 에러가 되는 거죠.

설정하기

#

개발 의존성으로 설치하고, 생성된 코드가 import할 패키지도 함께 설치합니다. React Query 훅과 목을 쓸 거라면 TanStack Query, MSW, Faker입니다.

npm install --save-dev orval msw @faker-js/faker
npm install @tanstack/react-query

그다음 프로젝트 루트에 orval.config.ts를 추가합니다. 아래 설정은 Orval 공식 문서의 예제와 거의 같습니다.

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: './openapi.yaml', // a path or a URL
    },
    output: {
      mode: 'single',
      target: './src/api/petstore.ts',
      schemas: './src/api/model',
      client: 'react-query',
      httpClient: 'fetch',
      mock: true, // MSW handlers plus Faker data
      override: {
        fetch: { includeHttpResponseReturnType: false },
      },
    },
  },
});

무엇이 생성될지는 client가 정합니다. 그냥 fetch나 axios 함수, React Query·Vue Query·Svelte Query·SWR용 훅, Angular 서비스, Zod 스키마 중에서 고를 수 있습니다. includeHttpResponseReturnType: false 줄은 fetch 클라이언트가 { data, status } 대신 응답 바디 자체를 반환하게 하는데, 컴포넌트 입장에서는 대개 이쪽이 편합니다.

명령어를 아무도 외울 필요가 없도록 스크립트도 추가해 둡니다.

{
  "scripts": {
    "api": "orval"
  }
}

npm run api를 실행하면 훅과 모델이 생성됩니다. 컴포넌트에서는 여느 React Query 훅처럼 쓰면 되고, 타입은 이미 다 채워져 있습니다.

import { useListPets } from './api/petstore';

export function PetList() {
  const { data: pets, isLoading } = useListPets();
  if (isLoading) return <p>Loading…</p>;
  return (
    <ul>
      {pets?.map((pet) => <li key={pet.id}>{pet.name}</li>)}
    </ul>
  );
}

스펙에서 필드 이름을 바꾸고 npm run api를 다시 돌리면, pet.name을 쓰는 곳마다 빨간 줄이 그어집니다. 앞에서 말한 어긋남 검사가 바로 이것이고, 돌리는 데 드는 비용은 0입니다.

목을 상대로 개발하기

#

mock: true를 켜면 Orval은 엔드포인트마다 MSW 요청 핸들러도 만듭니다. 응답 스키마 모양 그대로의 Faker 데이터를 돌려주는 핸들러들이고, 이걸 전부 모아 반환하는 함수도 하나 생깁니다. 그 목록을 브라우저에서는 MSW의 setupWorker에, 테스트에서는 setupServer에 넘기면, 앱은 이미 계약과 일치하는 가짜 백엔드를 상대로 돌아갑니다. 핸들러마다 오버라이드도 받을 수 있어서, 특정 페이로드나 빈 목록, 에러 상태를 돌려주는 테스트를 누가 픽스처를 손으로 짜지 않아도 만들 수 있습니다.

프론트엔드가 첫날부터 작업을 시작할 수 있는 건 이 덕분입니다. 목은 누군가 따로 관리해야 하는 별도의 산출물이 아닙니다. 클라이언트와 같은 스펙에서 매번 다시 생성되니, 스펙보다 뒤처질 수가 없죠.

Orval과 openapi-generator, openapi-typescript, Hey API 비교

#

넷 다 OpenAPI 스펙에서 출발하지만, 멈추는 지점이 다릅니다.

타입만 필요하다면 openapi-typescript가 가장 가볍고, 딱히 반박할 거리도 없습니다. openapi-generator는 스펙 하나로 여러 언어를 먹여 살려야 할 때 제값을 합니다. TypeScript 출력도 동작은 하지만, 읽다 보면 Java를 먼저 염두에 두고 만든 티가 납니다. Orval과 Hey API 사이에서는 대체로 취향 문제이고, 어느 쪽이 내놓는 코드를 읽는 게 더 편한지로 갈립니다. 제가 계속 Orval을 쓰는 건 목이 훅과 같은 실행에서 함께 나오기 때문이고, 두 팀이 일하는 방식을 바꾼 게 바로 그 기능이었습니다.

화려한 도구는 아닙니다. 그저 팀 사이의 말다툼 한 종류를 통째로 조용히 없애줄 뿐인데, 저는 그 거래라면 언제든 응할 생각입니다.

요약하면, 이 설계 우선 프로세스는 스프린트마다 다음 순서로 돌아갑니다.

1. 그 스프린트의 API 작업을 맡을 담당자를 백엔드와 프론트엔드에서 한 명씩 정합니다.
2. 두 사람이 스프린트 요구사항에 맞춰 OpenAPI 스키마를 작성(또는 수정)하고, 양쪽이 동의할 때까지 리뷰합니다.
3. 스키마를 저장소에 커밋합니다. 이제부터 이게 계약입니다.
4. 커밋된 스키마로 CI가 목 서버를 띄웁니다.
5. 프론트엔드는 목 서버를 상대로 개발하고, 그동안 백엔드는 실제 엔드포인트를 구현합니다.
6. 실제 서비스가 배포되면, 거기서 생성된 스펙이 다음 스프린트 스키마의 출발점이 됩니다.

어쩌다 시작했나

#

발단은 회고였습니다. API 계획이 얼마나 안 보이는지에 대해 피드백이 꽤 직설적이었거든요. 백엔드는 요구사항을 자기들 나름대로 해석해서 엔드포인트를 만들고, 프론트엔드는 응답 형태를 나중에야 알게 되고, 어긋난 부분은 통합 시점에, 그러니까 가장 비싼 순간에 터져 나왔습니다. 그래서 나온 제안이 양쪽을 계획 단계부터 끌어들이고, OpenAPI 스키마를 모든 것의 기준점으로 삼자는 것이었습니다.

프로세스

#

매주 백엔드 한 명, 프론트엔드 한 명, 이렇게 대표 두 명을 뽑습니다. 이들의 임무는 스프린트 요구사항을 이해하고 계획용 OpenAPI 스키마를 거기에 맞추는 것입니다. 둘이 함께 스키마를 리뷰하고 안 맞는 부분을 고치다 보면, 만들기 전에 양쪽 모두 정확히 뭘 만들지 알게 됩니다.

수정이 마무리되면 스키마를 저장소에 커밋하고, CI/CD가 그 yaml로 목 API를 생성합니다. 스프린트가 끝나면 다음 스프린트의 API 요구사항을 담은 새 yaml을 만들고, 같은 사이클을 반복합니다.

도구 관련 메모

#

yaml 시각화는 Swagger Editor면 충분합니다. 파일을 올리면 제대로 된 Swagger 문서로 렌더링해서 보여 줍니다.

CI/CD 파이프라인은 yaml을 받아서 목 서버를 띄울 수 있어야 합니다. Stoplight의 Prism이 널리 쓰이는 선택지이고, OpenAPI 3.1도 지원합니다.

npm install -g @stoplight/prism-cli
prism mock openapi.yaml

이렇게 하면 스키마의 모든 경로가 http://127.0.0.1:4010에서 서비스되고, 응답으로는 스키마의 examples가 그대로 돌아옵니다. 예를 들어 GET /lists/10을 호출하면 부록에 있는 예시 리스트가 옵니다. 계약도 제대로 지키게 합니다. 예제에서 API 키를 선언해 뒀기 때문에 X-API-Key 헤더가 없는 요청에는 401을 돌려주는데, 프론트엔드가 맞춰 개발해야 할 동작이 바로 이거죠. 컨테이너 안에서 돌릴 때는 바깥에서 접근할 수 있도록 -h 0.0.0.0을 붙이세요. openapi-mock은 응답을 무작위 데이터로 채워 주는, 좀 더 가벼운 대안입니다.

목 서버를 띄우기 전에 스키마를 린트해 두는 것도 좋습니다. 계약이 깨져 있으면 프론트엔드를 헷갈리게 하는 대신 빌드가 실패하니까요. Spectral은 한 줄짜리 룰셋만 있으면 바로 돌아갑니다.

npm install -g @stoplight/spectral-cli
echo 'extends: ["spectral:oas"]' > .spectral.yaml
spectral lint openapi.yaml

마지막으로, 이 스키마는 어디까지나 계획용 산출물입니다. 실제 API가 배포되면 각 서비스가 자기 openapi.json을 생성해야 하고, 그걸 내려받아 다음 계획에 다시 활용하면 됩니다.

왜 이 수고를 하나

#

논쟁이 가장 싼 곳으로 옮겨가기 때문입니다. 스키마를 쓰는 자리에 프론트엔드와 백엔드 엔지니어가 같이 앉아 있으면, 오해는 코드가 되기 전에 잡힙니다. API 요구사항은 스프린트 중간에 재협상되는 대신 한 번에 합의되고, 목 서버 덕분에 프론트엔드는 기다리지 않고 바로 시작하고, 중요한 디테일이 빠져나갈 틈도 훨씬 줄어듭니다. 두 쌍의 눈과 문서화된 계약을 다 통과해야 하니까요.

혁명적인 이야기는 하나도 없습니다. 그저 기계가 목으로 되돌려줄 수 있을 만큼 계획을 구체적으로 만들었을 뿐인데, 알고 보니 계획에 필요한 구체성이란 딱 그 정도더군요.

부록 A - yaml 예제

#

openapi: 3.1.0
info:
  title: MyApp Sprint 3
  description: Planning schema for sprint 3. Drives the mock server only.
  version: 0.3.0
servers:
  - url: https://api-mock.example.com/v1
tags:
  - name: lists
    description: Saved lists feature (PROJ-123)
security:
  - api_key: []
paths:
  /lists:
    get:
      tags: [lists]
      summary: Return the current user's saved lists
      operationId: getLists
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/List'
  /lists/{listId}:
    get:
      tags: [lists]
      summary: Find a list by ID
      operationId: getListById
      parameters:
        - name: listId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        '404':
          description: List not found
components:
  schemas:
    List:
      type: object
      required: [id, title]
      properties:
        id:
          type: integer
          format: int64
          examples: [10]
        title:
          type: string
          examples: [Weekend reading]
        itemCount:
          type: integer
          examples: [7]
  securitySchemes:
    api_key:
      type: apiKey
      name: X-API-Key
      in: header

기다림의 게임

#

전통적인 흐름은 직렬입니다. 백엔드가 API를 설계하고 구현한 뒤, 엔드포인트가 실제로 동작해야 프론트엔드가 통합을 시작합니다. 백엔드의 지연은 전부 프론트엔드 일정에 그대로 얹히는데, 릴리스 날짜가 적혀 있는 곳이 대개 프론트엔드 일정표입니다.

코드보다 계약이 먼저

#

스키마 우선 흐름에서는 양쪽이 거의 동시에 출발합니다. 코드가 한 줄도 없는 시점에 API 구조를 OpenAPI 스키마로 적어 둡니다. 모든 엔드포인트, 요청·응답 모델, 인증 방식, 에러 코드까지요. 이 문서가 프론트엔드와 백엔드 사이의 계약서가 됩니다.

효과는 바로 나타납니다. 만들기 전에 모두가 기능을 같은 모양으로 이해하게 됩니다. 백엔드가 구현 중인 동안 프론트엔드는 UI를 만들 수 있고요. 합의된 단일 진실 공급원 하나만 고치면 되니 변경도 빨리 돕니다. 게다가 스키마에서 바로 목 서버를 생성할 수 있어서, 진짜 엔드포인트가 하나도 없는 단계부터 프론트엔드 테스트가 시작됩니다.

실제로 돌리는 순서

#

1. 요구사항을 모읍니다. 뭘 만들든 똑같죠.
2. 스키마를 설계합니다. 엔드포인트, 요청/응답 모델, 인증, 에러 코드.
3. 프론트엔드와 백엔드 양쪽이 함께 리뷰합니다. 계약이 제값을 하는 순간이 바로 여기입니다.
4. 목 서버를 생성하고(Swagger, Postman 둘 다 됩니다) 프론트엔드는 그걸 상대로 통합을 진행합니다.
5. 백엔드는 같은 스키마에 맞춰 진짜 엔드포인트를 구현합니다.
6. 완성되는 대로 목을 진짜 엔드포인트로 갈아 끼우고, 계약이 지켜지는지 계속 테스트합니다.
7. 대화를 이어갑니다. 스키마는 살아 있는 문서지 석판이 아니니까요.

걸리는 부분

#

공짜는 아닙니다. 꼼꼼한 스키마를 미리 쓰는 데는 실제로 시간이 듭니다. 요구사항이 바뀌면 스키마부터 고쳐야 하고, 그 파장은 두 팀 모두에 미칩니다. 그리고 전원이 OpenAPI와 주변 도구에 최소한의 감은 갖고 있어야 하죠.

그래도 이 선행 투자가, 그 덕에 막을 수 있는 통합 지옥에 지는 걸 본 적이 없습니다. 프론트엔드는 첫날부터 달리기 시작하고, 논쟁은 깨진 빌드가 아니라 문서 위에서 벌어지게 됩니다.