Rihpig

Posted on Jun 10 • Originally published at apidog.com

깃 네이티브 API 테스트 및 개발 협업

OpenAPI 스펙은 API와 API 소비자 사이의 계약입니다. 문제는 이 계약이 실제 워크플로우의 어디에 존재하느냐입니다.

API 스펙이 별도 도구 안에만 있으면 쉽게 오래됩니다. 한 번 내보낸 뒤 잊히고, 구현이 바뀌어도 스펙은 업데이트되지 않습니다. 문서는 실제 API와 달라지고, 테스트 컬렉션은 따로 움직이며, 리뷰어는 스펙 변경 없이 코드만 승인하게 됩니다.

스펙 우선 모드(Spec-first Mode)는 이 흐름을 Git 중심으로 바꿉니다. OpenAPI 또는 Swagger 파일을 구현 코드와 같은 저장소에 두고, 브랜치·풀 리퀘스트·코드 리뷰 프로세스로 관리합니다. API 설계, 테스트, 문서화가 같은 스펙을 기준으로 동기화됩니다.

이 글에서는 Apidog에서 스펙 우선 프로젝트를 만들고, OpenAPI 파일을 편집하며, Git 워크플로우에 맞춰 팀과 동기화하는 방법을 단계별로 정리합니다.

스펙 우선 모드란 무엇인가요?

일반적인 API 도구에서는 UI에서 엔드포인트를 만들거나 기존 스펙을 가져온 뒤, 도구 내부 저장소에 API 정의를 보관합니다. Git 연동이 있더라도 보통은 “내보내기” 단계에 가깝습니다.

스펙 우선 모드에서는 작업의 기준이 파일입니다.

openapi.yaml 또는 openapi.json 파일이 Git 저장소에 존재합니다.
Apidog는 이 파일을 파싱해 API 구조를 보여줍니다.
파일을 코드 뷰에서 직접 편집하거나, 지원되는 항목은 양식 뷰로 편집합니다.
변경 사항은 Git 브랜치와 동기화됩니다.

즉, 스펙 파일이 항상 권위 있는 소스입니다. Apidog는 이 파일을 읽고, 편집하고, 저장소와 동기화합니다.

사전 준비

따라 하려면 다음이 필요합니다.

Apidog 계정
OpenAPI/Swagger 파일이 있는 Git 저장소, 또는 새로 시작할 빈 저장소
해당 저장소에 대한 쓰기 권한
OpenAPI 또는 Swagger 문법에 대한 기본 이해

예시 파일 구조는 다음처럼 단순하게 시작할 수 있습니다.

api-spec/
├── openapi.yaml
└── README.md

1단계: 스펙 우선 프로젝트 생성

Apidog에서 + 새 프로젝트를 클릭한 뒤 프로젝트 유형으로 스펙 우선 모드를 선택합니다.

그다음 Git 공급자를 연결합니다.

GitHub, GitLab, Azure DevOps 또는 Bitbucket 중 하나를 선택합니다.
조직 또는 작업 공간을 선택합니다.
기존 저장소를 선택하거나 새 저장소를 생성합니다.
동기화할 기본 브랜치를 선택합니다.

Apidog는 저장소의 기본 브랜치와 동기화됩니다. 기본 브랜치 이름이 main이 아니어도 선택한 브랜치 기준으로 동작합니다.

2단계: 웹훅 동기화 설정

설정 과정에서 웹훅 설치 옵션이 표시됩니다. 웹훅을 설치하면 팀원이 저장소에 푸시할 때 Apidog가 자동으로 변경 사항을 동기화합니다.

참고: 웹훅 설치에는 일반적으로 저장소에 대한 관리자 권한이 필요합니다. 관리자 권한이 없다면 이 단계는 건너뛰고, 나중에 수동으로 Git Pull을 실행하면 됩니다.

웹훅을 사용하면 다음 흐름으로 동작합니다.

팀원이 Git 저장소에 push
        ↓
저장소 웹훅 이벤트 발생
        ↓
Apidog가 변경 사항 자동 동기화
        ↓
팀 전체가 최신 스펙 확인

처음에 웹훅 설정을 건너뛰었다면 나중에 프로젝트 설정 > Git & 브랜치에서 추가할 수 있습니다.

3단계: 스펙 작업 공간 확인

프로젝트를 생성하면 스펙 작업 공간이 열립니다. 이 화면이 파일 편집과 Git 작업의 중심입니다.

주요 패널은 다음과 같습니다.

패널	역할
파일 탐색기	동기화된 저장소의 파일과 폴더 표시
API 구조 트리	파싱된 OpenAPI 콘텐츠 표시: 엔드포인트, 스키마, 정의, 개요
편집기	코드 뷰 또는 양식 뷰에서 파일 편집

구조 트리에서 엔드포인트를 클릭하면 Apidog가 소스 파일의 해당 섹션을 강조 표시합니다. API 구조를 보면서 실제 YAML 또는 JSON 위치로 바로 이동할 수 있습니다.

4단계: 스펙 파일 편집

코드 뷰에서 직접 편집

YAML, JSON, Markdown 파일은 코드 뷰에서 원시 텍스트로 편집할 수 있습니다.

예를 들어 openapi.yaml에 새 엔드포인트를 추가한다면 다음처럼 작성할 수 있습니다.

paths:
  /users/{userId}:
    get:
      summary: 사용자 조회
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 사용자 정보
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"

Apidog는 파일 내용을 별도 형식으로 변환하지 않습니다. 편집한 내용은 스펙 파일에 그대로 반영됩니다.

양식 뷰에서 구조화된 편집

지원되는 OpenAPI 노드에서는 양식 뷰로 전환해 구조화된 방식으로 편집할 수 있습니다.

양식 뷰는 다음 작업에 유용합니다.

YAML 구조를 직접 기억하지 않고 엔드포인트 추가
요청/응답 스키마 편집
보안 정의 업데이트
API 메타데이터 수정

양식 편집을 지원하지 않는 노드는 코드 뷰에서 편집합니다.

5단계: 유효성 검사와 문서 미리 보기

스펙 우선 모드에서는 편집 중에 유효성 검사와 문서 미리 보기를 바로 실행할 수 있습니다.

유효성 검사 실행

편집기 헤더에서 유효성 검사를 클릭합니다. 현재 스펙의 경고와 오류가 패널에 표시됩니다.

검사 대상에는 다음이 포함됩니다.

YAML 또는 JSON 구문 오류
필수 필드 누락
스키마 위반
명명 규칙 관련 문제

커밋하기 전에 이 단계에서 문제를 수정하면 리뷰어가 기본적인 스펙 오류를 수동으로 찾을 필요가 줄어듭니다.

문서 미리 보기

미리 보기를 클릭하면 현재 스펙이 API 문서로 어떻게 렌더링되는지 확인할 수 있습니다.

엔드포인트 미리 보기에는 두 개의 탭이 있습니다.

탭	내용
문서	생성된 엔드포인트 문서
직접 실행하기	엔드포인트 정의를 기반으로 한 실시간 요청 패널

스키마와 정의 항목에서는 렌더링된 문서 보기를 확인할 수 있습니다.

유효성 검사와 미리 보기는 같은 사이드 패널을 사용합니다. 하나를 열면 다른 하나는 자동으로 닫힙니다.

6단계: 팀 변경 사항 가져오기

다른 팀원이 저장소에 변경 사항을 푸시했다면 Apidog에서 가져옵니다.

스펙 작업 공간을 엽니다.
사이드바에서 현재 브랜치 이름을 클릭합니다.
Git Pull을 선택합니다.

웹훅 동기화가 활성화되어 있다면 저장소 푸시 이벤트에 따라 Apidog가 자동으로 pull을 수행합니다.

7단계: 변경 사항 커밋 및 푸시

Apidog에서 스펙 파일을 수정한 뒤 Git으로 반영합니다.

스펙 작업 공간에서 파일을 수정합니다.
사이드바에서 변경 사항을 클릭합니다.
수정, 추가, 이름 변경, 삭제된 파일을 확인합니다.
커밋 & 푸시를 클릭합니다.
커밋에 포함할 파일을 선택합니다.
커밋 메시지를 작성합니다.
푸시를 클릭합니다.

커밋 메시지는 구현 변경과 같은 기준으로 작성하는 것이 좋습니다.

docs(api): add user detail endpoint spec

또는

feat(api): update order schema response fields

이제 스펙 업데이트는 코드 변경과 동일한 풀 리퀘스트 워크플로우에서 검토할 수 있습니다. 팀원은 구현 코드와 API 계약을 한 곳에서 확인하고 댓글을 남기며 승인할 수 있습니다.

팁: 푸시하기 전에 로컬 편집 내용을 버리고 싶다면 모든 변경 사항 취소를 사용하세요.

8단계: 브랜치 작업

스펙 우선 모드는 브랜치 기반 협업을 지원합니다. Apidog는 Git 브랜치를 프로젝트 브랜치에 매핑하므로 기능 개발, 릴리스 준비, 병렬 작업에 맞춰 스펙 버전을 전환할 수 있습니다.

일반적인 작업은 다음과 같습니다.

작업	수행 방법
브랜치 전환	브랜치 이름 클릭 → 다른 브랜치 선택
기존 Git 브랜치 가져오기	새 브랜치 가져오기 클릭 → 브랜치 선택 → 가져오기
새 브랜치 생성	프로젝트 설정 > Git & 브랜치 → 새 브랜치
동기화 문제 해결	브랜치 설정에서 다시 동기화 사용
동기화 로그 보기	브랜치 작업 → 로그 보기

예를 들어 새 결제 API를 개발한다면 다음처럼 작업할 수 있습니다.

main
 └── feature/payment-api

feature/payment-api 브랜치에서 스펙을 수정하고, 구현 코드와 함께 PR을 생성하면 리뷰어는 API 계약과 구현을 같은 맥락에서 검토할 수 있습니다.

9단계: CI/CD와 통합

스펙이 Git에 있으면 CI/CD 파이프라인에 자연스럽게 포함할 수 있습니다.

가능한 자동화 예시는 다음과 같습니다.

모든 PR에서 스펙 린트 검사 실행
스펙이 main 브랜치에 병합될 때 문서 자동 생성
스펙 변경 시 API 테스트 실행
API 게이트웨이, 목 서버, SDK 생성기 등 다운스트림 시스템과 동기화

GitHub Actions 예시는 다음과 같습니다.

name: Validate and Test API Spec

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

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

      - name: Lint OpenAPI Spec
        run: npx spectral lint openapi.yaml

      - name: Run API Tests
        run: apidog run tests --spec openapi.yaml

이렇게 구성하면 API 스펙도 애플리케이션 코드와 같은 품질 게이트를 통과합니다.

대안: 스토리지 기반 프로젝트

외부 Git 저장소를 아직 연결할 준비가 되지 않았다면 Apidog의 스토리지 기반 스펙 우선 프로젝트를 사용할 수 있습니다.

스토리지 기반 프로젝트는 Apidog 내부 스토리지를 사용하지만 다음 기능을 제공합니다.

파일 기반 편집
유효성 검사 및 미리 보기
브랜치 관리

UI 레이블은 일부 다르게 표시됩니다.

Git 기반 프로젝트	스토리지 기반 프로젝트
Git Pull	동기화
Commit & Push	저장

팀이 준비되면 외부 Git 저장소로 마이그레이션할 수 있습니다.

요약

스펙 우선 모드를 사용하면 API 워크플로우가 Git 중심으로 정리됩니다.

스펙 우선 모드 이전	스펙 우선 모드 이후
스펙이 별도 도구에 존재	스펙이 Git 저장소에 존재
내보내기/가져오기로 동기화	푸시 또는 pull 기반으로 동기화
코드 리뷰와 분리된 스펙 검토	풀 리퀘스트에서 함께 검토
문서가 별도로 생성됨	편집 중 바로 미리 보기
스펙 변경과 테스트가 분리됨	스펙 업데이트로 테스트 트리거 가능

스펙 우선 모드는 OpenAPI 파일을 코드와 함께 버전 관리되는 API 계약으로 만듭니다. Apidog에서 스펙 우선 프로젝트를 생성하고 첫 번째 저장소를 연결해보세요.

DEV Community