Git 네이티브 API 워크플로우란 무엇이며 어떻게 구축하나요?

코드, CI 파이프라인, 리뷰, 릴리스 이력은 Git에 있습니다. API 사양도 같은 위치에 두면 변경 이력, 리뷰, 자동화를 동일한 방식으로 관리할 수 있습니다.

지금 Apidog를 사용해 보세요

Git 기반 API 워크플로는 OpenAPI 정의를 코드 저장소에 YAML 또는 JSON 파일로 유지하는 방식입니다. 사양을 편집하고, 커밋하고, 풀 리퀘스트로 리뷰하고, CI에서 검증합니다. 별도의 클라우드 데이터베이스나 내보내기/가져오기 루프가 필요 없습니다.

💡 Apidog는 Spec-First 모드를 통해 이 워크플로를 지원합니다. IDE 스타일 편집기에서 API를 설계하고, 원시 OpenAPI 파일을 GitHub 또는 GitLab과 양방향으로 동기화할 수 있습니다.

Git 기반 API 워크플로의 의미

Git 기반 API 워크플로는 API 사양을 코드처럼 다루는 방식입니다. OpenAPI 파일은 서비스 코드와 같은 저장소에 있고, 모든 변경은 Git 커밋으로 남습니다.

이 방식은 API 사양에 다음을 제공합니다.

• 버전 기록: 누가 언제 엔드포인트, 스키마, 응답을 변경했는지 추적할 수 있습니다. git blame도 사양 파일에 그대로 사용할 수 있습니다.
• 브랜치와 리뷰: 사양 변경은 풀 리퀘스트로 제출되고, 리뷰어는 병합 전에 diff를 확인합니다.
• 단일 진실 공급원: main 브랜치의 OpenAPI 파일이 API 계약입니다. 문서, 목업, 테스트, 코드 생성은 이 파일을 기준으로 동작합니다.

예를 들어 저장소 구조는 다음처럼 구성할 수 있습니다.

my-service/
├── src/
├── tests/
├── openapi/
│   └── openapi.yaml
└── package.json

사양 우선(spec-first) 접근 방식에서는 구현보다 API 계약을 먼저 정의합니다. 자세한 개념은 사양 우선 API 개발 가이드를 참고하세요.

클라우드 종속 API 사양의 문제점

많은 API 디자인 도구는 사양을 자체 클라우드 데이터베이스에 저장합니다. UI에서는 파일처럼 보이지만 실제로는 저장소에 있는 원시 YAML/JSON이 아닙니다.

이 방식은 다음 문제를 만들 수 있습니다.

리뷰가 분리됩니다

코드 변경은 GitHub 또는 GitLab에서 리뷰하고, 사양 변경은 별도 도구에서 리뷰합니다. 리뷰 컨텍스트가 분리되면 승인 상태가 어긋날 수 있습니다.

diff가 명확하지 않습니다

사양이 클라우드 데이터베이스에 있으면 풀 리퀘스트에서 줄 단위 diff를 보기 어렵습니다. 리뷰어는 실제 변경 내용을 확인하지 못한 채 “디자인 v3” 같은 추상적인 변경을 승인하게 됩니다.

내보내기/가져오기가 반복됩니다

CI에서 사양을 사용하려면 클라우드 도구에서 export한 뒤 저장소에 커밋해야 합니다. 이 과정에서 클라우드 사본과 Git 사본이 서로 달라질 수 있습니다.

자동화가 복잡해집니다

린터, 계약 테스트, 코드 생성 도구는 일반적으로 디스크에 있는 파일을 입력으로 받습니다. 사양이 클라우드에 잠겨 있으면 CI 전에 가져오기 단계가 추가됩니다.

API 사양을 코드로 취급하면 파일이 곧 사양이고, Git이 곧 기록이 됩니다. 이 원칙은 코드형 API 사양에서 더 자세히 다룹니다.

Apidog Spec-First 모드 작동 방식

Apidog Spec-First 모드는 Git 커밋과 브랜치를 중심으로 일하는 팀을 위한 워크플로입니다. API 사양을 원시 YAML 또는 JSON 파일로 유지하고, Apidog가 해당 파일을 Git 저장소와 양방향으로 동기화합니다.

1. IDE 스타일 OpenAPI 편집기에서 작성

Spec-First 모드에서는 양식이 아니라 코드 편집기에서 OpenAPI 파일을 작성합니다.

지원되는 편집 기능은 다음과 같습니다.

• YAML 및 JSON 구문 강조
• OpenAPI 및 Swagger 스키마 유효성 검사
• OpenAPI 키워드, 타입, $ref 자동 완성
• 파일 기반 편집
• 숨겨진 UI 전용 메타데이터 없음

즉, 저장소의 실제 파일을 직접 제어하면서도 API 디자인 도구의 편의성을 사용할 수 있습니다.

2. 원시 YAML/JSON 파일로 사양 관리

예를 들어 다음과 같은 openapi.yaml 파일을 저장소에 둘 수 있습니다.

openapi: 3.1.0
info:
  title: Orders API
  version: 1.2.0

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

components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, shipped, delivered]

이 파일을 수정하면 변경 내용은 Git diff로 확인할 수 있습니다.

git diff openapi/openapi.yaml

예를 들어 새 응답을 추가했다면 PR에서 다음처럼 명확한 변경 단위를 리뷰할 수 있습니다.

 responses:
   "200":
     description: Order found
+  "404":
+    description: Order not found

3. 자동 구문 분석과 탐색 가능한 개요 사용

Apidog는 파일을 입력하는 동안 OpenAPI 구조를 파싱하고 왼쪽 사이드바에 개요를 생성합니다.

탐색 가능한 항목은 다음과 같습니다.

• paths
• operation
• parameters
• responses
• schemas
• components

긴 OpenAPI 파일에서도 수백 줄을 직접 스크롤하지 않고 특정 엔드포인트나 스키마로 이동할 수 있습니다.

4. GitHub, GitLab, Azure DevOps와 동기화

Spec-First 모드는 Git 제공업체와 연결해 양방향 동기화를 수행합니다.

지원 방식은 다음과 같습니다.

• GitHub 직접 지원
• GitLab 직접 지원
• Azure DevOps는 Git 연결을 통해 지원

팀원이 원격 브랜치에 변경 사항을 푸시하면 Apidog에서 가져올 수 있습니다. Apidog에서 사양을 수정한 뒤 같은 브랜치에 커밋하고 푸시할 수도 있습니다.

5. Apidog 안에서 커밋, 푸시, 상태 확인

Apidog에서 다음 Git 작업을 처리할 수 있습니다.

• 변경 파일 확인
• 커밋 메시지 작성
• 커밋
• 푸시
• 동기화 상태 확인
• 푸시되지 않은 변경 취소

푸시가 완료되면 동기화 상태가 “방금 동기화됨”처럼 표시됩니다. 이 흐름은 OpenAPI 사양을 GitHub에 동기화 가이드에서도 확인할 수 있습니다.

설정 단계별 설명

다음은 저장소에서 Apidog Spec-First 프로젝트를 만들고 OpenAPI 사양을 동기화하는 기본 흐름입니다. 전체 참조는 Spec-First 모드 문서를 확인하세요.

1. 저장소에 OpenAPI 파일 준비

먼저 저장소에 OpenAPI 파일을 둡니다.

openapi/
└── openapi.yaml

아직 파일이 없다면 최소 구조로 시작할 수 있습니다.

openapi: 3.1.0
info:
  title: My API
  version: 0.1.0
paths: {}

2. Apidog에서 Spec-First 프로젝트 생성

Apidog에서 새 Spec-First 프로젝트를 만들고 Git 제공업체를 연결합니다.

선택해야 할 항목은 다음과 같습니다.

• Git 제공업체
• 저장소
• 추적할 브랜치
• OpenAPI 사양 파일 경로

일반적으로 추적 브랜치는 main 또는 API 사양 작업용 브랜치입니다.

3. 사양 파일 편집

Apidog 편집기에서 OpenAPI 파일을 엽니다.

수정할 수 있는 예시는 다음과 같습니다.

• 새 엔드포인트 추가
• 요청 파라미터 추가
• 응답 스키마 수정
• 공통 컴포넌트 스키마 정리
• 오류 응답 정의

예를 들어 /orders/{orderId}에 404 응답을 추가했다면 변경 내용은 파일에 그대로 반영됩니다.

4. 변경 파일 확인

Apidog는 마지막 동기화 이후 변경된 파일을 표시합니다.

확인할 항목은 다음과 같습니다.

• 수정된 파일
• 추가된 파일
• 삭제된 파일

커밋 전에 어떤 파일이 포함되는지 확인하면 불필요한 변경을 줄일 수 있습니다.

5. 커밋 메시지 작성

커밋 메시지는 변경 내용을 구체적으로 작성하는 것이 좋습니다.

좋은 예:

Add 404 response to getOrder

나쁜 예:

Update spec

API 사양도 코드와 마찬가지로 커밋 이력이 중요합니다. 나중에 git log나 git blame으로 변경 이유를 추적할 수 있어야 합니다.

6. 푸시

Apidog에서 커밋을 원격 브랜치로 푸시합니다.

푸시 후 팀원과 CI 파이프라인은 새 OpenAPI 사양을 사용할 수 있습니다.

7. 동기화 상태 확인

푸시가 완료되면 동기화 상태가 “방금 동기화됨”으로 표시되는지 확인합니다.

전체 루프는 다음과 같습니다.

가져오기 → 편집 → 커밋 → 푸시 → 동기화 상태 확인

이 과정에는 별도 export 단계가 없습니다. 저장소의 파일이 곧 API 사양입니다.

CI에서 OpenAPI 파일 활용하기

Git 기반 API 워크플로의 장점은 CI에서 사양을 바로 사용할 수 있다는 점입니다. 예를 들어 OpenAPI 파일을 린팅하거나 계약 테스트, 코드 생성에 연결할 수 있습니다.

예시 흐름은 다음과 같습니다.

PR 생성
→ OpenAPI 파일 변경 감지
→ 스펙 린팅
→ 계약 테스트
→ 문서 또는 SDK 생성
→ 리뷰 후 병합

GitHub Actions에서는 다음처럼 파일 변경을 기준으로 작업을 실행할 수 있습니다.

name: Validate OpenAPI

on:
  pull_request:
    paths:
      - "openapi/**"

jobs:
  validate-openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Show OpenAPI files
        run: ls -al openapi

사용 중인 린터나 코드 생성 도구가 있다면 openapi/openapi.yaml을 입력으로 연결하면 됩니다. 핵심은 사양이 클라우드 export 결과가 아니라 저장소의 실제 파일이라는 점입니다.

Spec-First 모드 vs Design-First 모드

Apidog는 두 가지 작업 방식을 지원합니다. 차이는 사양의 저장 위치와 편집 방식입니다.

항목	Spec-First 모드 (베타)	Design-First 모드
사양 저장소	Git의 원시 YAML/JSON 파일	Apidog 클라우드 프로젝트
주요 편집기	IDE 스타일 코드 편집기	시각적 양식 기반 UI
버전 관리	네이티브 Git: 커밋, 브랜치, diff	Apidog 기록 및 브랜치
양방향 Git 동기화	예: GitHub, GitLab, Azure DevOps	내보내기/가져오기를 통해
가장 적합한 경우	Git을 중심으로 일하는 팀	시각적 워크플로를 선호하는 팀

둘 중 하나가 항상 더 좋은 것은 아닙니다.

• 리뷰, 릴리스, CI가 이미 Git에서 실행된다면 Spec-First 모드가 적합합니다.
• 팀이 원시 OpenAPI를 거의 직접 편집하지 않고 시각적 양식 기반 편집을 선호한다면 Design-First 모드가 더 적합할 수 있습니다.

언제 Spec-First 모드를 사용해야 할까요?

다음 조건에 해당하면 Spec-First 모드를 고려하세요.

• API 사양 변경을 풀 리퀘스트로 리뷰해야 합니다.
• API 계약에 대해 git blame과 실제 커밋 기록이 필요합니다.
• CI에서 사양 린팅, 계약 테스트, 코드 생성을 실행합니다.
• 여러 엔지니어가 같은 사양을 편집합니다.
• 줄 단위 diff와 병합 가능한 변경이 중요합니다.
• 클라우드 도구에서 사양을 계속 export하는 과정이 번거롭습니다.

반대로 다음 상황이라면 시각적 클라우드 우선 접근 방식이 더 나을 수 있습니다.

• 팀원이 원시 YAML/JSON을 작성하지 않습니다.
• 비엔지니어가 API 사양을 주로 관리합니다.
• 양식 기반 편집기가 더 생산적입니다.
• Git 리뷰보다 도구 내부 리뷰가 더 익숙합니다.

구현 시 체크리스트

Spec-First 워크플로를 적용할 때는 다음을 확인하세요.

• [ ] OpenAPI 파일 경로를 저장소 안에 명확히 정합니다.
• [ ] main 또는 전용 브랜치를 기준 브랜치로 정합니다.
• [ ] 사양 변경은 PR을 통해 리뷰하도록 규칙을 맞춥니다.
• [ ] 커밋 메시지는 변경 내용을 구체적으로 작성합니다.
• [ ] CI에서 OpenAPI 파일을 검증하도록 설정합니다.
• [ ] 문서, 목업, 테스트, 코드 생성이 같은 사양 파일을 바라보게 합니다.
• [ ] Apidog 동기화 상태를 확인한 뒤 PR을 생성합니다.

자주 묻는 질문

Git 기반 API 워크플로란 무엇인가요?

Git 기반 API 워크플로는 OpenAPI 사양을 Git 저장소의 파일로 저장하고, 커밋, 브랜치, 풀 리퀘스트로 모든 변경을 관리하는 방식입니다. 사양은 애플리케이션 코드와 같은 리뷰 및 버전 관리 프로세스를 따릅니다.

Apidog Spec-First 모드는 GitHub와 GitLab을 지원하나요?

예. Spec-First 모드는 GitHub 및 GitLab과 직접 양방향으로 동기화됩니다. Azure DevOps는 Git 연결을 통해 지원됩니다. 저장소와 브랜치를 선택하면 Apidog가 편집 내용과 원격 브랜치를 동기화합니다.

OpenAPI 파일을 원시 YAML 또는 JSON으로 편집할 수 있나요?

예. Spec-First 모드는 원시 YAML 및 JSON용 IDE 스타일 편집기를 제공합니다. OpenAPI 및 Swagger에 대한 구문 강조, 스키마 유효성 검사, 자동 완성을 지원합니다. 왼쪽 사이드바 개요를 통해 대규모 사양도 빠르게 탐색할 수 있습니다.

Spec-First 모드와 Design-First 모드의 차이점은 무엇인가요?

Spec-First 모드는 사양을 Git의 원시 파일로 유지하고, 코드 편집기와 양방향 Git 동기화를 사용합니다. Design-First 모드는 시각적 양식 기반 편집기를 사용하며, 사양은 Apidog 클라우드 프로젝트에 저장됩니다.

CI에서 OpenAPI 사양을 바로 사용할 수 있나요?

예. 사양이 저장소의 파일로 존재하므로 CI에서 해당 파일을 직접 읽을 수 있습니다. 린팅, 계약 테스트, 문서 생성, SDK 생성 같은 작업에 연결할 수 있습니다.

결론

Git 기반 API 워크플로는 코드와 API 계약을 같은 프로세스 안에 둡니다. 사양은 파일이 되고, 파일은 커밋이 되며, 커밋은 기존 리뷰와 CI 파이프라인을 통과합니다.

Apidog Spec-First 모드는 이 흐름을 위해 IDE 스타일 OpenAPI 편집기, 탐색 가능한 개요, 양방향 Git 동기화를 제공합니다. 원시 YAML 또는 JSON을 편집하고, 명확한 커밋 메시지로 푸시한 뒤, 동기화 상태를 확인하면 됩니다.

Spec-First 모드를 사용해보고 API 사양을 Git 워크플로 안으로 가져오세요.