계약 파이프라인

백엔드의 OpenAPI(스웨거) 명세에서 프론트엔드 연동 코드를 자동 생성해, 프론트와 백엔드가 어긋나지 않게 합니다.

개요

계약 파이프라인은 백엔드가 노출하는 openapi.json(스웨거 문서의 원본 데이터)을 단일 진실(single source of truth)로 삼아, 프론트엔드의 타입·TanStack Query 훅·MSW mock을 자동 생성합니다. 백엔드 API가 바뀌면 프론트 연동 코드도 한 번의 생성으로 따라가므로, 어떤 백엔드 템플릿을 골라도 프론트와의 연동 방식이 동일합니다.

흐름

[백엔드]  Zod 스키마 (단일 진실)
   │ nestjs-zod 가 산출
   ▼
openapi.json (스웨거 원본)
   │
   ├─ 사람용: Swagger UI 문서 화면 (/swagger-ui)
   │
   └─ 기계용: orval 코드 생성
        ├─ TypeScript 타입
        ├─ TanStack Query 훅 (axios 인스턴스 + Query Key Factory)
        └─ MSW mock 서버 → 백엔드 완성 전에도 프론트 개발 시작 가능

openapi.json은 평소 보던 스웨거와 같은 것입니다. 스웨거 UI 화면이 읽는 그 원본 JSON을, 프론트 코드 생성기도 똑같이 읽습니다.

사용

생성된 풀스택 프로젝트의 packages/contracts에 orval 설정이 들어 있습니다.

# 1) 백엔드를 띄운다
pnpm api:dev          # http://localhost:3000/openapi.json 노출
 
# 2) 연동 코드를 생성한다
pnpm contracts:generate

생성물(packages/contracts/src/api/):

• model/ — 요청·응답 타입
• endpoints/ — TanStack Query 훅 (useXxxQuery, useXxxMutation)
• *.msw.ts — MSW mock 핸들러

명세 전달: 개발은 URL, 릴리즈는 패키지

프론트엔드 API 패턴과의 관계

프론트엔드의 API Integration 패턴은 “프론트가 백엔드를 호출하는” 방법(axios 인스턴스·인터셉터)을 다룹니다. 계약 파이프라인은 그 연동 코드를 백엔드 명세에서 자동 생성해 주는 단계로, 둘은 함께 동작합니다.