Git으로 OpenAPI 스펙 버전 관리하는 방법

OpenAPI 스펙은 계약입니다. 스펙이 변경되면 클라이언트가 오작동하고, 목업이 오래되어 무용지물이 되며, 더 이상 존재하지 않는 API에 대해 테스트가 통과하는 문제가 발생합니다. 따라서 스펙을 다른 코드처럼 다루십시오: Git에 저장하고, 브랜치로 관리하고, 검토하고, 모든 변경 사항에 대해 유효성을 검사하세요.

이 가이드는 Git을 사용한 OpenAPI 버전 관리에 대해 처음부터 자세히 설명합니다. 파일이 어디에 위치해야 하는지, 브랜치를 어떻게 관리하는지, 검토자가 스펙 차이점에서 실제로 무엇을 확인하는지, 그리고 Apidog에서 변경 사항을 바로 푸시하는 방법에 대해 다룹니다. 이 가이드를 마치면 팀 전체가 신뢰할 수 있는 워크플로우를 갖게 될 것입니다.

OpenAPI 스펙을 버전 관리해야 하는 이유

위키나 공유 드라이브에 있는 스펙은 기록이 없습니다. 지난 화요일에 누가 POST /orders 페이로드를 변경했는지, 왜 변경했는지 알 수 없습니다. Git이 이 문제를 해결해줍니다.

openapi.yaml을 버전 관리하면 다음 네 가지를 무료로 얻을 수 있습니다:

• 히스토리. 모든 변경 사항은 작성자, 타임스탬프 및 메시지가 포함된 커밋으로 기록됩니다.
• 책임 추적. git blame openapi.yaml을 사용하면 누가 필수 필드를 언제 추가했는지 알 수 있습니다.
• 롤백. 계약을 파기한 잘못된 병합이 있었나요? 해당 커밋을 되돌리면 작동하는 스펙으로 돌아갈 수 있습니다.
• 검토. 스펙 변경 사항은 풀 리퀘스트를 통해 진행되므로, 다른 사람이 배포되기 전에 차이점을 확인할 수 있습니다.

이것은 Git-native API 워크플로우의 기반입니다. 스펙은 소스 코드이며, 소스 코드는 Git에 저장됩니다.

저장소에서 스펙 파일이 위치하는 곳

간단하고 예측 가능하게 유지하세요. 대부분의 팀은 단일 openapi.yaml 파일을 저장소 루트 또는 api/ 폴더에 둡니다:

my-service/
├── api/
│ └── openapi.yaml
├── src/
└── README.md

여러 주요 버전을 병렬로 유지 관리하는 경우, 각 주요 버전별로 파일을 나누어 관리합니다:

api/
├── api-v1.yaml
└── api-v2.yaml

이렇게 하면 파괴적 변경 사항이 격리됩니다. api-v1.yaml은 기존 클라이언트를 위해 고정된 상태로 유지되고 api-v2.yaml은 발전합니다. 또한 각 파일이 하나의 이유로만 변경되므로 차이점(diff)이 작아지고 검토가 빨라집니다. 스펙을 이러한 방식으로 다루는 것이 API spec as code의 핵심 아이디어입니다.

하나의 규칙을 선택하고 문서화하세요. 최악의 결과는 두 개의 파일이 서로 '진정한' 스펙이라고 주장하는 것입니다.

스펙 변경을 위한 브랜칭 전략

스펙을 위한 특별한 브랜칭 모델이 필요하지 않습니다. 코드에서 이미 사용하는 방식을 재사용하세요. main 브랜치에서 분기하여 변경 사항을 만들고, PR을 엽니다.

스펙 브랜치를 쉽게 스캔할 수 있도록 하는 명명 규칙:

api/ 접두사는 "이 PR이 계약을 변경한다"는 것을 한눈에 알려줍니다. 검토자와 CI는 이를 기준으로 필터링할 수 있습니다. 파괴적 변경의 경우, 명시적인 breaking- 접두사는 추가적인 검토와 아마도 버전 업이 필요하다는 플래그 역할을 합니다.

브랜치를 단명하게 유지하세요. 2주 동안 유지되는 스펙 브랜치는 다른 사람들의 변경 사항과 충돌할 것입니다. 작고 집중된 브랜치는 깔끔하게 병합됩니다.

풀 리퀘스트에서 스펙 변경 사항 검토하기

이것이 버전 관리가 진가를 발휘하는 부분입니다. 스펙 PR은 계약 변경이며, 계약 변경은 실제 검토를 받아야 마땅합니다.

검토자가 서식과 씨름하지 않고 변경 사항을 읽을 수 있도록 YAML을 차이점(diff) 친화적인 방식으로 작성하세요:

paths:
 /orders/{orderId}:
 get:
 summary: Get an order
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 "200":
 description: Order found
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"

일관된 들여쓰기와 한 줄에 하나의 속성을 사용하면 단일 필드 추가가 한 줄 차이점으로 나타납니다. 이것이 목표입니다.

검토자가 확인해야 할 사항:

• 파괴적 변경. 요청에 필수 필드가 추가되었습니까? 응답 필드가 제거되거나 이름이 변경되었습니까? enum 값이 손실되었습니까? 각 변경 사항은 기존 클라이언트를 손상시킬 수 있습니다.
• 하위 호환성. 새로운 선택적 필드와 새로운 엔드포인트는 안전합니다. 기존 형태의 변경은 그렇지 않습니다.
• 명명 및 일관성. 새로운 엔드포인트가 나머지 API의 대소문자 및 복수형과 일치합니까?
• 완전성. 모든 새로운 작업에는 summary, 응답 스키마 및 오류 응답이 필요합니다.
• 예시. 현실적인 예시는 문서와 목업을 유용하게 만듭니다.

파괴적 변경 감지를 위해서는 육안보다는 도구에 의존하세요. CI 단계(아래 설명)는 PR의 스펙을 main과 비교하여 호환되지 않는 변경 사항을 발견하면 빌드를 실패시킬 수 있습니다. 사람은 이러한 부분을 놓치지만, 차이점(diff) 도구는 그렇지 않습니다.

Apidog에서 커밋 및 푸시

원시 YAML을 수동으로 편집하는 것도 가능하지만, 실시간 유효성 검사가 있는 시각적 편집기가 더 빠르고 실수를 조기에 잡아냅니다. Apidog의 Spec-First 모드는 양방향 Git 동기화를 제공합니다. 도구를 떠나지 않고 UI에서 스펙을 편집하고, 커밋하고, 저장소로 푸시할 수 있습니다. 팀원의 변경 사항을 같은 방식으로 다시 가져올 수도 있습니다.

흐름은 다음과 같습니다:

1. Git 저장소를 연결하고 Apidog가 스펙 파일을 가리키도록 합니다.
2. 시각적 편집기에서 엔드포인트, 스키마 및 예시를 편집합니다.
3. Apidog는 깔끔하고 차이점(diff) 친화적인 YAML을 파일에 다시 기록합니다.
4. 브랜치에 커밋하고 푸시한 다음, 평소처럼 PR을 엽니다.

Apidog는 YAML을 일관되게 직렬화하므로, 차이점(diff)이 작고 검토하기 쉬우며, 불필요한 재정렬이나 재포맷팅이 없습니다. 전체 설정은 Apidog Spec-First 모드 문서에서 확인할 수 있습니다. 특정 제공업체에 파일을 저장하려면 GitHub에 OpenAPI 스펙 동기화하기를 참조하세요.

CI 유효성 검사 훅

유효하지 않은 스펙이 main에 도달하도록 허용하지 마세요. 풀 리퀘스트 검사에 유효성 검사를 연결하여 손상된 계약이 자동으로 빌드를 실패하도록 만드세요.

최소한의 GitHub Actions 단계:

name: Validate OpenAPI
on: [pull_request]
jobs:
 lint:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Lint spec
 run: npx @redocly/cli lint api/openapi.yaml

성장함에 따라 더 많은 검사를 추가하세요:

• 구조적 및 스타일 문제에 대해 스펙을 린트합니다.
• 유효한 OpenAPI 3.x로 파싱되는지 검증합니다.
• main과 차이점(diff)을 비교하여 파괴적 변경 사항을 감지하고 PR에 플래그를 지정합니다.

이러한 검사는 몇 초 만에 실행되며, 사람이 대충 훑어볼 때 놓칠 수 있는 오류를 잡아냅니다.

모범 사례

몇 가지 습관은 시간이 지나도 스펙 버전 관리를 건전하게 유지시켜 줍니다:

• 시맨틱 버전 관리를 사용하세요. info.version 필드를 업데이트합니다. 파괴적 변경은 새로운 메이저 버전을 의미하고, 하위 호환 가능한 추가 기능은 마이너 버전을 올립니다.
• 변경 로그를 유지하세요. 스펙 옆에 있는 짧은 CHANGELOG.md는 소비자에게 버전 간에 변경된 내용을 알려줍니다.
• 작은 차이점(diff)을 배포하세요. PR당 하나의 논리적 변경만 포함합니다. 큰 스펙 PR은 노이즈 속에 파괴적 변경 사항을 숨깁니다.
• 설명적인 커밋 메시지를 작성하세요. "환불 요청에 refundReason 추가"가 "스펙 업데이트"보다 좋습니다.
• 병합된 스펙을 main에서 직접 편집하지 마세요. 오타의 경우에도 항상 브랜치를 만드세요.

자주 묻는 질문

OpenAPI 스펙에서 파괴적 변경 사항을 어떻게 감지하나요?

CI에서 풀 리퀘스트를 main의 버전과 비교하는 스펙 차이점(diff) 도구를 실행하세요. oasdiff와 같은 도구는 각 변경 사항을 파괴적 변경, 비파괴적 변경 또는 미분류로 분류하며, 파괴적 변경이 발생하면 빌드를 실패시킬 수 있습니다. 이는 수동 검토에서는 놓칠 수 있는 제거된 필드, 새로운 필수 매개변수 및 변경된 유형을 잡아냅니다.

하나의 OpenAPI 파일을 유지해야 하나요, 아니면 여러 개로 분할해야 하나요?

단일 openapi.yaml 파일로 시작하세요. 검토하고 버전 관리하기 가장 쉽습니다. 파일이 커지거나 여러 주요 버전을 병렬로 유지 관리하는 경우, 주요 버전별로(api-v1.yaml, api-v2.yaml) 분할하거나 $ref를 사용하여 스키마를 별도의 파일로 나눕니다. 너무 일찍 분할하지 마세요. 읽기 쉬운 하나의 파일이 파편화된 다섯 개의 파일보다 낫습니다.

YAML을 수동으로 작성하지 않고도 스펙을 버전 관리할 수 있나요?

네. Apidog의 Spec-First 모드를 사용하면 시각적 편집기에서 스펙을 편집하고 변경 사항을 양방향으로 Git에 동기화할 수 있습니다. 일관된 YAML을 작성하므로, 전체 Git 히스토리와 검토를 유지하면서도 차이점(diff)이 깔끔하고 풀 리퀘스트가 읽기 쉽습니다.