OpenAPI 스펙은 API와 해당 API를 사용하는 소비자 간의 계약입니다. 그런데 이 계약은 어디에 존재할까요?
너무 자주, API 스펙은 고립된 도구 안에 있습니다. 한 번 내보내지고 잊히며, 구현이 변경되어도 거의 업데이트되지 않습니다. 문서는 흐트러지고, 테스트 컬렉션은 달라지며, 리뷰어들은 해당 스펙 업데이트를 보지 않고 코드 변경을 승인합니다.
스펙 우선 모드(Spec-first Mode)는 이 모델을 뒤집습니다. OpenAPI 또는 Swagger 파일은 구현 코드와 함께 Git 저장소에 직접 저장되어 진실의 원천이 됩니다. 모든 스펙 변경은 여러분이 이미 사용하는 것과 동일한 브랜치, 풀 리퀘스트 및 검토 프로세스를 거칩니다. API 설계, 테스트, 문서화가 모두 자동으로 동기화됩니다.
이 튜토리얼에서는 Apidog에서 스펙 우선 프로젝트를 설정하고, 팀과 함께 스펙을 편집하며, Git 워크플로우에 따라 모든 것을 동기화하는 방법을 안내해 드리겠습니다.
스펙 우선 모드란 무엇인가요?
일반적인 API 프로젝트에서는 시각적 양식을 통해 엔드포인트를 생성하거나 기존 스펙을 시작점으로 가져옵니다. 도구는 API 정의를 내부적으로 저장하며, Git 통합(가능한 경우)은 내보내기 단계입니다.
스펙 우선 모드는 다릅니다. 주요 작업 공간은 파일 기반입니다:
openapi.yaml또는openapi.json파일이 여러분의 저장소에 존재합니다.- Apidog는 이 파일들을 파싱하여 탐색 가능한 API 구조를 생성합니다.
- 파일을 직접 편집하거나(지원되는 양식을 통해) 편집할 수 있습니다.
- 변경 사항은 자동으로 Git에 동기화됩니다.
스펙 파일은 항상 권위 있는 소스입니다. Apidog는 이를 읽고, 쓰고, 저장소와 동기화 상태를 유지합니다.
사전 준비
튜토리얼을 따라 하려면 다음이 필요합니다:
- Apidog 계정 (무료 티어로도 가능)
- OpenAPI/Swagger 파일이 있는 Git 저장소, 또는 새롭게 시작할 빈 저장소
- 저장소에 대한 쓰기 권한
- OpenAPI 또는 Swagger 구문에 대한 기본적인 이해
1단계: 스펙 우선 프로젝트 생성
Apidog에서 + 새 프로젝트를 클릭하고 프로젝트 유형으로 스펙 우선 모드를 선택하세요.
다음으로, Git 공급자를 연결하세요:
- 공급자(GitHub, GitLab, Azure DevOps 또는 Bitbucket)를 선택하세요.
- 조직 또는 작업 공간을 선택하세요.
- 기존 저장소를 선택하거나 새로 생성하세요.
- 동기화할 메인 브랜치를 선택하세요.
Apidog는 저장소의 기본 브랜치와 동기화됩니다. 만약 이름이 main이 아니라면, Apidog가 자동으로 적용합니다.
2단계: 웹훅 동기화 설정 (권장)
설정 중에 웹훅을 설치하는 옵션이 표시됩니다. 이는 팀이 저장소에 푸시할 때마다 자동 동기화를 가능하게 합니다.
참고: 웹훅 설치는 일반적으로 저장소에 대한 관리자 권한이 필요합니다. 관리자 액세스 권한이 없다면 이 단계를 건너뛰세요. Git Pull을 사용하여 수동으로 동기화할 수 있습니다.
웹훅의 이점:
- 팀이 변경 사항을 푸시 → Apidog가 자동으로 동기화합니다.
- 수동으로 새로 고칠 필요가 없습니다.
- 모든 팀원이 최신 스펙 상태를 확인할 수 있습니다.
처음에 웹훅 설정을 건너뛰었다면, 나중에 프로젝트 설정 > Git & 브랜치에서 추가할 수 있습니다.
3단계: 스펙 작업 공간 탐색
생성 후 프로젝트는 파일 기반 편집 및 Git 작업의 중앙 허브인 스펙 작업 공간을 엽니다.
세 개의 패널이 함께 작동합니다:
| 패널 | 표시 내용 |
|---|---|
| 파일 탐색기 | 동기화된 저장소의 모든 파일 및 폴더 |
| API 구조 트리 | 파싱된 OpenAPI 콘텐츠: 엔드포인트, 스키마, 정의, 개요 |
| 편집기 | 코드 뷰 또는 양식 뷰에서 파일 편집 |
구조 트리에서 엔드포인트를 클릭하면 → Apidog가 소스 파일에서 해당 섹션을 강조 표시합니다. 탭을 전환할 필요 없이 상위 수준 API 보기에서 하위 수준 YAML로 이동할 수 있습니다.
4단계: 스펙 파일 편집
코드 뷰: 직접 편집
대부분의 파일(YAML, JSON, Markdown)의 경우 코드 뷰를 사용하여 원시 텍스트를 편집하세요.
여러분의 편집 내용은 파일에 그대로 유지됩니다. Apidog는 이를 변환하거나 별도로 저장하지 않습니다. 스펙 파일은 진실의 단일 원천으로 남습니다.
양식 뷰: 구조화된 편집
지원되는 OpenAPI 노드(엔드포인트, 스키마, 정의 및 API 개요)의 경우 양식 뷰로 전환하세요.
양식 뷰는 다음과 같은 경우에 유용합니다:
- YAML 구조를 암기하지 않고도 모든 필수 필드를 사용하여 엔드포인트를 추가할 때
- 스키마를 시각적으로 편집할 때
- 보안 정의 및 API 메타데이터를 업데이트할 때
노드가 양식 편집을 지원하지 않으면 Apidog는 코드 뷰에 머무르게 합니다.
5단계: 즉시 유효성 검사 및 미리 보기
스펙 우선 모드에는 실시간 유효성 검사 및 문서 미리 보기 기능이 포함되어 있어 외부 도구가 필요 없습니다.
유효성 검사를 통한 문제 확인
편집기 헤더에서 유효성 검사를 클릭하세요. 현재 스펙의 모든 경고 및 오류가 패널에 표시됩니다.
배지는 총 문제 수를 표시합니다. 다음을 확인할 수 있습니다:
- 구문 오류
- 누락된 필수 필드
- 스키마 위반
- 명명 규칙 문제
커밋하기 전에 문제를 수정하세요. 팀의 리뷰어들이 이러한 문제를 수동으로 찾을 필요가 없습니다.
문서 미리 보기
미리 보기를 클릭하여 스펙이 API 문서로 어떻게 렌더링되는지 확인하세요.
엔드포인트의 경우 미리 보기는 두 개의 탭을 포함합니다:
| 탭 | 내용 |
|---|---|
| 문서 | 생성된 엔드포인트 문서 |
| 직접 실행하기 | 엔드포인트 정의를 기반으로 한 실시간 요청 패널 |
스키마 및 정의의 경우 미리 보기에는 렌더링된 문서 보기가 표시됩니다.
유효성 검사와 미리 보기는 동일한 사이드 패널을 공유합니다. 하나를 열면 다른 하나는 자동으로 닫힙니다.
6단계: 팀의 업데이트 풀 받기
협업자가 저장소에 변경 사항을 푸시하면 Apidog로 가져옵니다:
- 스펙 작업 공간을 엽니다.
- 사이드바에서 현재 브랜치 이름을 클릭합니다.
- Git Pull을 선택합니다.
웹훅 동기화가 활성화되어 있으면 Apidog는 저장소 푸시 이벤트에 따라 자동으로 풀을 수행하므로 수동 단계가 필요 없습니다.
7단계: 변경 사항 커밋 및 푸시
Apidog에서 파일을 편집한 후, 변경 사항을 Git으로 다시 보냅니다:
- 스펙 작업 공간에서 변경 사항을 만듭니다.
- 사이드바에서 변경 사항을 클릭하여 수정된, 추가된, 이름이 변경된, 삭제된 파일을 확인합니다.
- 커밋 & 푸시를 클릭합니다.
- 포함할 파일을 선택합니다.
- 커밋 메시지를 작성합니다.
- 푸시를 클릭합니다.
이제 스펙 업데이트는 코드 변경 사항과 동일한 풀 리퀘스트 워크플로우에 나타납니다. 팀원들은 구현과 API 계약을 한 곳에서 검토, 댓글 작성 및 승인할 수 있습니다.
팁: 푸시하기 전에 로컬 편집 내용을 버리고 싶다면 모든 변경 사항 취소를 사용하세요.
8단계: 브랜치 작업
스펙 우선 모드는 완전한 브랜치 기반 협업을 지원합니다. Apidog는 Git 브랜치를 프로젝트 브랜치에 매핑하여 스펙 버전을 전환할 수 있도록 합니다.
일반적인 브랜치 작업
| 작업 | 수행 방법 |
|---|---|
| 브랜치 전환 | 브랜치 이름 클릭 → 다른 브랜치 선택 |
| 기존 Git 브랜치 가져오기 | 새 브랜치 가져오기 클릭 → 선택 → 가져오기 |
| 새 브랜치 생성 | 프로젝트 설정 > Git & 브랜치 → 새 브랜치 |
| 동기화 문제 해결 | 브랜치 설정에서 다시 동기화 사용 |
| 동기화 로그 보기 | 브랜치 작업 → 로그 보기 |
브랜치 관리는 Git에서 예상하는 방식과 동일하게 작동합니다. 기능 브랜치, 릴리스 및 병렬 개발이 모두 올바르게 동기화됩니다.
9단계: CI/CD와 통합
스펙이 Git에 있기 때문에 자동화 파이프라인에 자연스럽게 통합됩니다:
- Apidog 유효성 검사 또는 Spectral과 같은 도구를 사용하여 모든 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 Pull이 동기화로 변경됩니다.
- Commit & Push가 저장으로 변경됩니다.
팀이 준비되면 언제든지 외부 Git으로 마이그레이션하세요.
요약
스펙 우선 모드를 사용하면 API 워크플로우가 다음과 같이 변경됩니다:
| 스펙 우선 모드 이전 | 스펙 우선 모드 이후 |
|---|---|
| 스펙은 별도의 도구에 존재 | 스펙은 Git 저장소에 존재 |
| 동기화를 위해 내보내기/가져오기 | 푸시 시 자동 동기화 |
| 코드 리뷰 외부에서 검토 진행 | 풀 리퀘스트에서 검토 진행 |
| 문서가 별도로 생성됨 | 편집 중 미리 보기 |
| 스펙 변경과 테스트가 단절됨 | 스펙 업데이트로 테스트가 트리거됨 |
스펙 우선 모드는 OpenAPI 파일을 버전 관리되고, 검토되며, 항상 코드와 일치하는 진정한 계약으로 만듭니다.
시도해 볼 준비가 되셨나요? Apidog에서 스펙 우선 프로젝트를 생성하고 첫 번째 저장소를 연결해보세요.