DEV Community

Cover image for Git 유지하며 OpenAPI 협업: 파일 중심 팀 협업 방식
Rihpig
Rihpig

Posted on • Originally published at apidog.com

Git 유지하며 OpenAPI 협업: 파일 중심 팀 협업 방식

OpenAPI 팀 협업은 사양이 Git으로 이동하는 순간부터 흔들리기 쉽습니다. Git이 사양 저장소로 부적합해서가 아니라, Git의 리뷰 도구가 주로 코드를 검토하는 엔지니어를 위해 설계되어 있기 때문입니다. API 설계에는 QA, 프론트엔드, 제품 관리자도 참여해야 하지만, 이들은 PR diff만으로는 사양을 읽고 검토하고 테스트하기 어렵습니다.

오늘 Apidog를 사용해 보세요

팀이 이미 OpenAPI 사양을 YAML 또는 JSON 파일로 리포지토리에 저장하는 파일 기반 접근 방식을 사용하고 있다면, 다음과 같은 상황을 겪었을 가능성이 큽니다.

  • 사양은 Git에서 버전 관리되지만, 비엔지니어는 별도 미리보기 화면을 봐야 합니다.
  • 질문은 Slack DM이나 이슈로 흩어집니다.
  • 프론트엔드는 백엔드 구현 전까지 실제로 테스트하기 어렵습니다.
  • 문서, 목(Mock), 테스트, 알림이 사양 파일과 자동으로 연결되지 않습니다.

API 사양을 코드로 다루는 방식은 Git을 단일 정보원으로 만드는 데 유용합니다. 이 글에서는 그다음 단계, 즉 Git에 있는 OpenAPI 파일을 유지하면서 Apidog 같은 협업 계층을 붙이는 방법을 다룹니다.

Git만으로는 해결되지 않는 API 협업 문제

Git은 변경 이력, 브랜치, 풀 리퀘스트, diff를 잘 처리합니다. 하지만 OpenAPI 사양을 팀 전체가 함께 사용하는 순간 다음 요구사항이 생깁니다.

1. 비엔지니어가 사양에 직접 주석을 달기 어렵다

QA 엔지니어가 openapi.yaml의 특정 응답 스키마에서 문제를 발견해도, PR diff의 특정 줄에 질문을 남기는 방식은 자연스럽지 않습니다.

예를 들어 QA가 다음을 확인해야 한다고 가정해 보겠습니다.

responses:
  "422":
    description: 유효성 검사 오류
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/ValidationError"
Enter fullscreen mode Exit fullscreen mode

QA 입장에서는 YAML 줄 번호보다 다음 질문이 더 중요합니다.

  • code 값은 enum으로 제한되는가?
  • message는 사용자에게 노출 가능한 문구인가?
  • 프론트엔드에서 필드별 오류를 표시할 수 있는가?

GitHub PR은 코드 리뷰에는 적합하지만, API 문서를 읽는 이해관계자에게는 진입 장벽이 있습니다.

2. 현재 브랜치 기준 목(Mock) 서버가 필요하다

프론트엔드 개발자는 백엔드 구현이 끝나기 전에 API 응답을 테스트해야 합니다. 하지만 Git에 있는 YAML 파일만으로는 자동 목 서버가 생기지 않습니다.

수동으로는 다음처럼 실행할 수 있습니다.

npx @stoplight/prism-cli mock api/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

하지만 이 방식은 다음 문제가 있습니다.

  • 브랜치별 목 URL 관리가 어렵습니다.
  • 팀원이 로컬에서 직접 실행해야 합니다.
  • PR마다 최신 사양을 반영했는지 확인해야 합니다.
  • 프로덕션 문서와 개발 중 사양을 분리하기 어렵습니다.

3. 변경 알림을 역할별로 라우팅하기 어렵다

/payments 응답 스키마가 변경되면 프론트엔드, 모바일, QA가 알아야 합니다. 반면 /admin 내부 API 변경은 내부 백오피스 팀만 알면 됩니다.

Git 웹훅은 “파일이 변경됨”은 알려줄 수 있지만, 다음처럼 의미 있는 API 변경 알림을 만들려면 추가 계층이 필요합니다.

POST /payments 응답 스키마가 변경되었습니다.
영향 대상: Web, Mobile, QA
브랜치: feature/payment-v2
Enter fullscreen mode Exit fullscreen mode

4. 문서 접근 제어가 세밀하지 않다

공개 GitHub 리포지토리에 있는 사양은 누구나 읽을 수 있습니다. 비공개 리포지토리는 접근을 제한할 수 있지만, 다음과 같은 API 문서 권한 모델은 Git만으로 구현하기 어렵습니다.

  • 외부 파트너는 공개 API만 볼 수 있음
  • 내부 팀은 관리 API까지 볼 수 있음
  • QA는 테스트 환경 문서를 볼 수 있음
  • 고객사는 특정 버전 문서만 볼 수 있음

즉, Git은 사양의 단일 정보원으로 유지하되, 협업 계층이 필요합니다.

협업 계층이 해야 할 일

좋은 구조는 단순합니다.

Git repository
  └── openapi.yaml
        ├── 문서
        ├── 목 서버
        ├── 주석 및 리뷰
        ├── 알림
        └── CI/CD 테스트
Enter fullscreen mode Exit fullscreen mode

핵심은 Git을 대체하지 않는 것입니다. OpenAPI 파일은 계속 Git에 커밋되고, 협업 도구는 그 파일을 읽어 팀 워크플로우에 연결해야 합니다.

범주 예시 강점 Git 위에 추가되는 기능
호스팅된 사양 플랫폼 Stoplight, SwaggerHub UI, 주석, 접근 제어 자체 사양 사본을 유지하는 경우가 많음
파일-네이티브 협업 계층 Apidog Spec-First 모드, Redocly 커밋된 파일 기반 작업 문서, 목, 리뷰, CI 계층 연결
Git-네이티브 API 클라이언트 Bruno, Insomnia 파일 동기화, 컬렉션 관리 주로 요청 실행 계층에 집중

도구를 선택할 때는 “Git 연동이 되는가?”만 보지 말고 다음을 함께 확인해야 합니다.

  • Git의 OpenAPI 파일을 단일 정보원으로 유지하는가?
  • 사양에서 바로 문서를 생성하는가?
  • 브랜치별 목 서버를 제공하는가?
  • 주석이 API 요소에 연결되는가?
  • CI/CD에서 계약 테스트를 실행할 수 있는가?
  • 알림을 경로 또는 태그 기준으로 라우팅할 수 있는가?

Bruno는 Git 처리에 강하지만 요청 계층에서 멈춘다

Bruno는 파일 기반 API 클라이언트 워크플로우에 강점이 있습니다. 특히 Bruno Ultimate는 파일 기반 컬렉션 저장, Git 통합, SSO, SCIM, 비밀 관리자 훅, 감사 로그 같은 기능을 제공합니다.

다음 요구사항이라면 Bruno는 적합할 수 있습니다.

  • API 요청 컬렉션을 Git으로 관리하고 싶다.
  • Postman 대신 파일 기반 클라이언트를 쓰고 싶다.
  • 요청 실행과 환경 변수를 코드처럼 관리하고 싶다.

하지만 Bruno는 주로 요청 계층에 집중합니다. 다음 기능은 별도 도구가 필요합니다.

  • 커밋된 OpenAPI 파일에서 문서 자동 생성
  • 브랜치별 목 서버 자동 생성
  • 사양 경로 변경에 따른 역할별 알림
  • API 문서 접근 제어
  • 사양 기반 계약 테스트와 협업 컨텍스트 연결

이미 Stoplight로 문서와 목 서버를 운영하고 있고 Bruno를 추가로 도입한다면, Stoplight를 대체하는 것이 아니라 Bruno를 병행하는 구조가 됩니다. 이 구조가 맞을 수도 있지만, 도구별 책임 범위를 명확히 해야 합니다.

Apidog Spec-First 모드로 Git 기반 협업 계층 만들기

Apidog의 Spec-First 모드(현재 베타)는 Git에 커밋된 openapi.yaml을 권위 있는 소스로 읽고, 그 위에 협업 기능을 추가하는 방식입니다. 사양을 별도 데이터베이스로 포크하는 대신, Git 파일을 중심으로 문서, 목, 주석, 테스트를 연결하는 구조입니다.

실제 적용 흐름은 다음과 같습니다.

1단계: Git 리포지토리 연결

Apidog에서 프로젝트를 생성한 뒤 GitHub, GitLab 또는 Bitbucket 리포지토리를 연결합니다. 그런 다음 OpenAPI 파일 경로를 지정합니다.

예:

repository: github.com/example/payment-service
spec path: api/openapi.yaml
branch: main
Enter fullscreen mode Exit fullscreen mode

연결 절차는 apidog-git-integration-sync 가이드를 참고할 수 있습니다.

예시 OpenAPI 파일은 다음과 같습니다.

# api/openapi.yaml
openapi: "3.1.0"
info:
  title: 결제 API
  version: "2.4.0"

paths:
  /payments:
    post:
      summary: 결제 생성
      operationId: createPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentRequest"
      responses:
        "201":
          description: 결제 생성됨
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentResponse"
        "422":
          description: 유효성 검사 오류
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"

components:
  schemas:
    PaymentRequest:
      type: object
      required: [amount, currency, source]
      properties:
        amount:
          type: integer
          description: 가장 작은 통화 단위 (예: 센트)
        currency:
          type: string
          enum: [usd, eur, gbp]
        source:
          type: string
          description: 결제 수단 토큰

    PaymentResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, completed, failed]

    ValidationError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
Enter fullscreen mode Exit fullscreen mode

2단계: PR diff가 아니라 사양 화면에서 리뷰하기

Git 연결 후 Apidog는 OpenAPI 사양을 대화형 문서로 렌더링합니다. 팀원은 엔드포인트, 스키마, 응답 예시에 직접 주석을 남길 수 있습니다.

예를 들어 QA가 POST /payments를 검토하면서 다음을 남길 수 있습니다.

idempotency-key 헤더가 필요하지 않나요?
중복 결제 방지를 위해 요청 헤더에 명시하는 것이 좋겠습니다.
Enter fullscreen mode Exit fullscreen mode

이때 QA는 YAML 파일을 직접 수정하거나 GitHub 커밋 권한을 가질 필요가 없습니다.

엔지니어는 피드백을 반영해 openapi.yaml을 수정합니다.

paths:
  /payments:
    post:
      summary: 결제 생성
      parameters:
        - name: idempotency-key
          in: header
          required: true
          schema:
            type: string
          description: 중복 결제 방지를 위한 멱등성 키
Enter fullscreen mode Exit fullscreen mode

그 후 브랜치에 커밋하고 PR을 생성합니다.

git checkout -b feature/payment-idempotency
git add api/openapi.yaml
git commit -m "Add idempotency key header to payments API"
git push origin feature/payment-idempotency
Enter fullscreen mode Exit fullscreen mode

주석은 줄 번호가 아니라 API 요소에 연결되므로, 사양이 변경되어도 대화 맥락을 유지하기 쉽습니다.

3단계: 브랜치별 목(Mock) 서버 생성

Spec-First 모드를 사용하면 사양 브랜치별로 목 서버를 만들 수 있습니다.

예를 들어 다음 브랜치가 있다고 가정합니다.

main
feature/payment-v2
feature/refund-api
Enter fullscreen mode Exit fullscreen mode

각 브랜치는 서로 다른 API 형태를 가질 수 있습니다.

main                  → 안정 버전 목 서버
feature/payment-v2    → 결제 v2 개발용 목 서버
feature/refund-api    → 환불 API 개발용 목 서버
Enter fullscreen mode Exit fullscreen mode

프론트엔드 개발자는 백엔드 구현을 기다리지 않고 브랜치별 목 URL을 사용해 UI를 개발할 수 있습니다.

이 방식은 다음 문제를 줄입니다.

  • 로컬 목 서버 수동 실행
  • 브랜치별 응답 스키마 혼동
  • 백엔드 구현 완료 전 프론트엔드 대기
  • 최신 사양 반영 여부 확인

4단계: API 변경 알림을 팀별로 라우팅

사양의 경로 또는 스키마가 변경되면 Apidog에서 구성된 채널로 알림을 보낼 수 있습니다.

예:

/payments/* 변경 → #frontend-payments, #mobile-payments
/admin/* 변경    → #internal-admin-api
/refunds/* 변경  → #qa-api-changes
Enter fullscreen mode Exit fullscreen mode

Slack 또는 Teams를 사용하는 경우 다음 문서를 참고해 수신 웹훅을 구성할 수 있습니다.

Apidog의 알림 설정에서는 엔드포인트 태그 또는 경로 접두사 기준으로 채널을 바인딩할 수 있습니다.

시험판에서 특히 확인할 항목은 다음입니다.

  • 태그별 알림이 가능한가?
  • 경로 prefix별 라우팅이 가능한가?
  • 변경 유형별 알림 필터링이 가능한가?
  • 문서 접근 권한이 조직 역할과 맞게 매핑되는가?

CI/CD에 OpenAPI 검증과 계약 테스트 연결하기

협업 계층은 채팅 알림뿐 아니라 CI/CD에 연결될 때 더 유용합니다. 기본 구조는 다음과 같습니다.

push / pull_request
  ├── OpenAPI lint
  ├── OpenAPI schema validation
  ├── contract test
  └── report / notification
Enter fullscreen mode Exit fullscreen mode

OpenAPI 린팅에는 Spectral 또는 Redocly CLI를 사용할 수 있습니다. Apidog CLI를 함께 사용하면 커밋된 사양에 대해 계약 테스트를 실행할 수 있습니다.

예시 GitHub Actions 워크플로우입니다.

# .github/workflows/api-spec.yml
name: API 사양 유효성 검사 및 테스트

on:
  push:
  pull_request:

jobs:
  validate-and-test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: OpenAPI 사양 유효성 검사 (Spectral)
        run: |
          npm install -g @stoplight/spectral-cli
          spectral lint api/openapi.yaml --ruleset .spectral.yaml

      - name: Apidog 계약 테스트 실행
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          npx apidog-cli run \
            --project-id ${{ vars.APIDOG_PROJECT_ID }} \
            --test-suite "결제 API 스모크" \
            --environment staging
Enter fullscreen mode Exit fullscreen mode

예시 .spectral.yaml은 다음처럼 시작할 수 있습니다.

extends: ["spectral:oas"]

rules:
  operation-operationId:
    severity: error

  operation-description:
    severity: warn

  no-empty-servers:
    description: servers는 비어 있으면 안 됩니다.
    given: $.servers
    then:
      function: truthy
Enter fullscreen mode Exit fullscreen mode

OpenAPI 사양은 API가 제공해야 하는 계약입니다. 커밋된 사양과 실행 중인 서비스가 어긋나면 CI에서 실패하게 만드는 것이 핵심입니다.

Git 기반 API 워크플로우 전체 구조는 git-native-api-workflow에서 더 자세히 볼 수 있습니다.

파일 기반 팀을 위한 도구 비교

파일 기반 OpenAPI 협업을 평가할 때는 기능을 항목별로 확인하는 것이 좋습니다. 아래 표의 “시험판에서 확인” 항목은 요금제, 베타 상태, 조직 설정에 따라 달라질 수 있습니다.

기능 Stoplight SwaggerHub Apidog Spec-First 모드, 베타
Git을 권위 있는 소스로 사용 선택 사항, 기본적으로 자체 복사본 선택 사항 예
설계 단계 주석 예 예 예
브랜치별 목(Mock) 예 부분적 예
역할 기반 문서 접근 예 예 시험판에서 확인
교차 프로젝트 스키마 재사용 예 예 시험판에서 확인
CI/CD 계약 테스트 Prism을 통해 제한적 예, Apidog CLI
사용자 지정 린트 규칙 Spectral을 통해 제한적 시험판에서 확인
SSO/SCIM 유료 등급 엔터프라이즈 시험판에서 확인
알림 라우팅 웹훅을 통해 제한적 예
파일-네이티브, 이중 복사본 없음 아니오 아니오 예, Spec-First

SwaggerHub를 포함한 더 넓은 비교는 swaggerhub-vs-apidog-collaboration을 참고하십시오.

적용 체크리스트

기존 OpenAPI 리포지토리에 협업 계층을 붙일 때는 다음 순서로 진행하는 것이 좋습니다.

1. OpenAPI 파일 위치 확정
2. main 브랜치의 사양을 기준으로 문서 생성
3. feature 브랜치에서 목 서버 동작 확인
4. QA/프론트엔드가 사양에 주석을 남기는 흐름 테스트
5. Slack 또는 Teams 알림 라우팅 구성
6. CI에서 lint + contract test 실행
7. 접근 제어와 외부 문서 공개 범위 검증
Enter fullscreen mode Exit fullscreen mode

실제 평가 시에는 다음 질문을 기준으로 PoC를 설계하십시오.

  • Git의 openapi.yaml이 계속 단일 정보원인가?
  • UI에서 편집한 변경 사항은 Git 브랜치와 PR로 연결되는가?
  • 브랜치별 목 URL이 안정적으로 제공되는가?
  • 비엔지니어가 Git 권한 없이 리뷰할 수 있는가?
  • CI 실패 시 어떤 리포트가 남는가?
  • 내부 API와 외부 API 문서를 분리할 수 있는가?

FAQ

Apidog 주석과 Git PR 리뷰를 함께 사용할 수 있나요?

네. 두 흐름은 목적이 다릅니다.

Git PR 리뷰는 YAML 변경 사항을 검토하는 엔지니어에게 적합합니다. Apidog 주석은 문서 형태의 API를 검토하는 제품, QA, 프론트엔드 이해관계자에게 적합합니다.

권장 흐름은 다음과 같습니다.

1. Apidog 문서 화면에서 QA/프론트엔드가 피드백 작성
2. 엔지니어가 openapi.yaml 수정
3. Git 브랜치에 커밋
4. PR에서 엔지니어 리뷰
5. 병합 후 문서, 목, 테스트 업데이트
Enter fullscreen mode Exit fullscreen mode

커밋된 파일은 두 흐름 모두의 단일 정보원으로 유지됩니다.

누군가 Apidog에서 사양을 편집하면 어떻게 되나요?

Spec-First 모드에서는 Apidog UI에서 변경한 내용을 Git에 커밋으로 다시 푸시하는 흐름을 사용할 수 있습니다.

일반적인 흐름은 다음과 같습니다.

UI에서 사양 편집
  → 브랜치에 커밋
  → Git에서 PR 생성
  → 코드 리뷰
  → main에 병합
Enter fullscreen mode Exit fullscreen mode

다만 팀에 따라 “Git에서만 편집할지” 또는 “UI 편집도 허용할지”를 정해야 합니다. 동기화 방향은 실제 운영 규칙에 영향을 주므로 시험판에서 반드시 확인해야 합니다.

Spec-First 모드 단계별 가이드는 spec-first-mode-apidog-beta-walkthrough를 참고하십시오.

여러 OpenAPI 파일이 있는 모노레포에서도 사용할 수 있나요?

모노레포에서는 다음처럼 여러 사양 파일을 둘 수 있습니다.

services/
  payments/
    api/openapi.yaml
  refunds/
    api/openapi.yaml
  admin/
    api/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog는 여러 프로젝트를 지원하며, 각 프로젝트를 서로 다른 파일 경로에 연결할 수 있습니다.

시험판에서 확인할 항목은 다음입니다.

  • 단일 Apidog 프로젝트가 여러 사양 파일에 매핑될 수 있는가?
  • 프로젝트 간 공통 스키마를 재사용할 수 있는가?
  • 공통 린트 규칙을 여러 프로젝트에 적용할 수 있는가?
  • 모노레포 브랜치 전략과 목 서버 생성 방식이 맞는가?

Redocly와 비교하면 어떤가요?

Redocly CLI는 파일 기반 OpenAPI 린팅, 번들링, 문서 생성에 강합니다. Redocly의 호스팅 플랫폼은 검토와 팀 기능을 추가합니다.

비교 관점은 다음과 같습니다.

  • Redocly CLI: 파일 기반 검증과 문서 생성에 강점
  • Redocly 호스팅 플랫폼: 협업 기능 추가
  • Apidog Spec-First: Git 파일을 기준으로 문서, 목, 계약 테스트, 알림을 하나의 플랫폼에 연결

파일 기반 파이프라인을 직접 조립하고 싶다면 Redocly CLI가 유용합니다. Git의 사양 파일을 중심으로 협업, 목, 테스트까지 묶고 싶다면 Apidog 같은 협업 계층을 평가할 수 있습니다.

OpenAPI 이니셔티브 자체 도구는 어떤가요?

OpenAPI 이니셔티브는 사양 자체를 발행하지만 협업 플랫폼을 제공하지는 않습니다. 따라서 팀은 OpenAPI를 구현하는 도구 생태계 중에서 선택해야 합니다.

특히 OpenAPI 3.1을 사용한다면 다음을 직접 테스트해야 합니다.

  • 3.1 문법을 완전히 지원하는가?
  • JSON Schema 2020-12를 올바르게 처리하는가?
  • 린터, 목 서버, 문서 생성기가 같은 방식으로 해석하는가?
  • 계약 테스트에서 3.1 스키마를 정확히 검증하는가?

결론

OpenAPI 사양을 Git에 저장했다면 파일 관리 문제는 해결한 것입니다. 하지만 협업 문제는 별개입니다.

팀에는 여전히 다음이 필요합니다.

  • 비엔지니어가 사양에 직접 주석을 남기는 방식
  • 브랜치별 목 서버
  • API 변경에 대한 역할별 알림
  • 내부/외부 문서 접근 제어
  • CI/CD 계약 테스트
  • Git 파일과 문서/목/테스트의 자동 연결

이 계층이 Git을 대체할 필요는 없습니다. 오히려 Git을 단일 정보원으로 유지하고, 그 위에 문서, 목, 리뷰, 알림, 테스트를 연결해야 합니다.

현재 Stoplight나 공유 문서가 협업을 처리하고 Git이 버전 관리를 처리하고 있다면, Apidog Spec-First 모드가 통합하려는 구조와 가깝습니다. 아직 베타이므로 문서 접근 제어, 교차 프로젝트 스키마 재사용, 알림 세분성처럼 팀에 중요한 항목을 중심으로 시험판을 실행한 뒤 도입 여부를 결정하는 것이 좋습니다.

Apidog를 다운로드하고 기존 OpenAPI 리포지토리의 브랜치에 연결해, 현재 Git 워크플로우에 협업 계층을 붙이는 방식을 직접 확인해 보십시오.

Top comments (0)