제가 함께 일했던 API 팀은 보통 두 가지 방식으로 나뉘었습니다.
첫 번째 방식은 OpenAPI 스펙을 직접 작성해 specs/ 디렉터리에 커밋하고, Git을 단일 진실 공급원으로 두는 것입니다. 두 번째 방식은 시각적 API 디자이너에서 엔드포인트를 만들고, 필요할 때 스펙을 내보낸 뒤, CI가 실패하면 UI와 YAML 사이의 차이를 다시 맞추는 것입니다.
둘 다 써봤습니다. 첫 번째 방식은 초반에는 느리지만 시간이 지날수록 안정적입니다. 두 번째 방식은 빠르게 시작할 수 있지만, 스펙과 실제 저장소 사이의 불일치를 관리해야 합니다.
Apidog는 오랫동안 두 번째 방식에 더 가까웠습니다. 시각적 디자이너는 강력했지만, YAML을 Git 중심으로 다루는 워크플로우에서는 왕복 편집이 부담이었습니다.
그러다 4월 중순, 새 프로젝트 생성 화면에 스펙 우선 모드(베타)가 추가되었습니다. 출시 직후가 아니라 실제 사이드 프로젝트의 OpenAPI 스펙으로 한나절 정도 사용해 본 뒤 정리했습니다. 이 글은 Apidog의 스펙 우선 모드를 실제로 설정하고 사용할 때 확인해야 할 부분에 초점을 맞춥니다.
스펙 우선 모드가 바꾸는 것
Apidog에는 이제 두 가지 프로젝트 모드가 있습니다.
기본 모드는 기존 Apidog 방식입니다. + 새 프로젝트를 누르고, 폴더 트리와 시각적 폼에서 엔드포인트, 파라미터, 응답 등을 정의합니다. OpenAPI 스펙은 내부적으로 생성됩니다. YAML에 익숙하지 않은 팀에는 여전히 적합합니다.
스펙 우선 모드는 다릅니다. 시각적 폼 대신 .yaml 또는 .json 파일을 직접 편집하는 코드 편집기가 열립니다. 그리고 Git 저장소와 양방향으로 동기화됩니다.
즉, OpenAPI 스펙은 UI에서 생성된 결과물이 아니라 저장소에 있는 실제 파일입니다.
스펙 우선 모드에서 제공되는 핵심 기능은 다음과 같습니다.
- OpenAPI YAML/JSON 파일 직접 편집
- 구문 강조
- OpenAPI 스키마 기반 자동 완성
- 입력 중 실시간 경로 파싱
- 파일에서 생성되는 엔드포인트 개요
- Git 저장소와 양방향 동기화
- Apidog UI에서 커밋 및 푸시
YAML의 문제는 단순히 문법이 어렵다는 것이 아닙니다. 파일이 길어지면 구조를 한눈에 보기 어렵다는 점이 더 큽니다. Apidog의 스펙 우선 모드는 이 부분을 사이드바 개요로 보완합니다. 파일은 그대로 유지하면서, 탐색은 UI에서 할 수 있습니다.
핵심은 소유권입니다. 스펙 우선 모드에서는 API 스펙의 원본이 Apidog 내부 데이터가 아니라 Git 저장소의 파일입니다. Apidog는 그 파일을 편집하고 탐색하기 위한 인터페이스가 됩니다.
설정 방법
아래는 실제로 제가 사용한 설정 순서입니다. Git 인증 시간을 제외하면 10분 안에 끝납니다.
1. 스펙 우선 모드로 프로젝트 생성
Apidog에서 다음 경로로 이동합니다.
+ 새 프로젝트 → 일반 → 스펙 우선 모드
기본 모드가 “권장”으로 표시되기 때문에 무심코 기본 모드를 선택하기 쉽습니다. 스펙 우선 워크플로우를 테스트하려면 반드시 스펙 우선 모드 타일을 선택해야 합니다.
2. Git 저장소 연결
프로젝트 생성 화면에서 Git 저장소와 연결 섹션으로 이동합니다.
다음 항목을 선택합니다.
- Git 공급자
- 조직
- 저장소
- 메인 브랜치
저는 GitHub 저장소를 연결했습니다. 연결이 완료되면 Apidog가 해당 브랜치의 .yaml 및 .json 파일을 작업 공간으로 동기화합니다.
3. 프로젝트 정보 입력
이후 다음 정보를 설정합니다.
- 프로젝트 이름
- 팀 권한
- 저장소 연결 정보
마지막으로 생성을 누릅니다.
4. OpenAPI 파일 편집
동기화가 끝나면 YAML 또는 JSON 파일을 엽니다.
예를 들어 OpenAPI 경로를 추가한다면 다음과 같은 구조를 직접 편집합니다.
paths:
/store/token:
post:
summary: Create store token
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
responses:
'200':
description: Token created
편집하는 동안 왼쪽 사이드바의 경로 개요가 업데이트됩니다. 특정 엔드포인트를 클릭하면 해당 YAML 위치로 이동할 수 있습니다.
VS Code에서 OpenAPI 확장을 사용해 본 적이 있다면 익숙한 경험입니다. 차이는 Apidog 안에서 Git 동기화, 탐색, API 작업 공간이 함께 제공된다는 점입니다.
5. 변경 사항 커밋 및 푸시
오른쪽 상단의 커밋 및 푸시 버튼을 누릅니다.
대화 상자에는 다음 항목이 표시됩니다.
- 변경된 파일 목록
- 커밋 메시지 입력 필드
- 푸시 버튼
- 모든 변경 사항 폐기 버튼
별도의 스테이징 단계는 없습니다. 변경 사항 목록에 있는 파일이 커밋 대상입니다. 스펙 파일을 수정하고 바로 커밋하는 워크플로우라면 충분히 단순합니다.
6. 동기화 상태 확인
왼쪽 하단의 동기화 표시기를 확인합니다.
예를 들어 다음과 같은 상태를 볼 수 있습니다.
- 방금 동기화됨
- 원격보다 뒤처짐
- 로컬 변경 사항 있음
저는 이 표시기를 계속 확인했습니다. 모달 창보다 더 자주 보게 되는 상태 정보입니다. 표시기가 정상이라면 Apidog 작업 공간과 Git 저장소가 같은 상태라는 뜻입니다.
실제 사용 중 확인한 점
하루 정도 사용하면서 눈에 띈 부분은 세 가지입니다.
1. 개요 업데이트가 빠릅니다
여러 OpenAPI 편집기는 저장 시점에 다시 파싱합니다. 그래서 경로를 추가한 뒤 사이드바에 반영되기까지 지연이 있습니다.
Apidog의 스펙 우선 모드에서는 입력하는 동안 개요가 거의 즉시 업데이트되었습니다. 덕분에 사이드바를 단순 상태 표시가 아니라 실제 탐색 도구로 사용할 수 있었습니다.
2. Git 동기화는 실제로 양방향입니다
Apidog를 열어 둔 상태에서 로컬 클론의 동일한 파일을 수정하고 터미널에서 푸시해 봤습니다.
Apidog는 원격 변경을 감지했고, 동기화 표시기는 뒤처진 상태로 바뀌었습니다. 이후 한 번의 동기화로 변경 사항이 편집기에 반영되었습니다.
이 워크플로우는 팀에서 특히 중요합니다.
예를 들어 한 명은 Vim 또는 VS Code에서 YAML을 직접 수정하고, 다른 한 명은 Apidog에서 같은 스펙을 탐색하며 수정할 수 있습니다. 둘 다 같은 Git 저장소의 파일을 기준으로 작업합니다.
3. 같은 프로젝트 안에서 기본 모드로 되돌릴 수는 없습니다
프로젝트를 만들 때 스펙 우선 모드를 선택하면, 그 프로젝트는 스펙 우선 프로젝트가 됩니다.
중간에 기본 시각적 디자이너 모드로 전환하는 방식은 아닙니다. 내부 데이터 모델이 다르기 때문입니다.
팀에서 두 방식을 모두 써야 한다면 다음처럼 운영할 수 있습니다.
Git 저장소의 OpenAPI 스펙
↓
스펙 우선 프로젝트
↓
별도 시각 모드 프로젝트에서 동일 스펙 가져오기
완전히 매끄러운 방식은 아니지만, 스펙의 원본을 Git에 유지하고 두 워크플로우를 병행하는 방법은 가능합니다.
언제 사용하면 좋은가
스펙 우선 모드는 다음과 같은 팀에 적합합니다.
- OpenAPI YAML/JSON을 직접 작성하는 팀
- Git을 API 스펙의 단일 진실 공급원으로 쓰는 팀
- CI에서
spectral lint같은 검증을 실행하는 팀 - OpenAPI 스펙에서 SDK 또는 문서를 생성하는 팀
- 스펙 변경을 Pull Request로 리뷰하는 팀
- Apidog의 UI는 쓰고 싶지만 스펙 파일은 저장소에 유지하고 싶은 팀
예를 들어 저장소에서 다음과 같은 검증을 이미 하고 있다면 잘 맞습니다.
name: lint-openapi
on:
pull_request:
paths:
- "specs/**/*.yaml"
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npx @stoplight/spectral-cli lint specs/openapi.yaml
이런 팀에서는 Apidog가 스펙 파일을 대체하는 것이 아니라, 스펙 파일을 더 편하게 편집하고 탐색하는 도구가 됩니다.
아직 기본 모드가 더 나은 경우
반대로 다음 상황이라면 기본 모드가 더 적합합니다.
- 팀원이 OpenAPI 구조에 익숙하지 않음
- YAML을 직접 수정하는 것이 진입 장벽이 됨
- API 설계를 주로 시각적 폼에서 진행함
- 비개발자도 API 정의에 자주 참여함
- 같은 프로젝트 안에서 시각적 편집과 스펙 직접 편집을 계속 오가야 함
스펙 우선 모드는 온보딩 편의성보다 파일 충실도와 Git 중심 워크플로우를 우선합니다. 팀의 대부분이 OpenAPI에 익숙하지 않다면 기본 모드가 더 현실적인 선택입니다.
정리
스펙 우선 개발은 그동안 종종 트레이드오프였습니다.
YAML 파일을 직접 관리하면 Git과 CI에는 좋지만, API 도구의 시각적 탐색 기능을 포기해야 했습니다. 반대로 시각적 디자이너를 쓰면 편하지만, 저장소의 스펙과 도구 내부 상태가 어긋날 수 있었습니다.
Apidog의 스펙 우선 모드는 이 둘 사이의 간격을 줄입니다.
- 저장소의 파일이 원본입니다.
- Apidog 편집기는 그 파일을 직접 다룹니다.
- 사이드바 개요는 파일에서 생성됩니다.
- Git 동기화는 별도 내보내기 단계가 아니라 기본 워크플로우입니다.
이미 OpenAPI 스펙을 Git에서 관리하고 있다면 테스트해 볼 만합니다. 새 프로젝트를 만들 때 스펙 우선 모드를 선택하고, 기존 저장소를 연결한 뒤 첫 커밋까지 진행해 보세요. 설정은 짧게 끝납니다. 실제 팀 워크플로우에 맞는지는 며칠간 PR, CI, 동기화 흐름까지 함께 확인해 보면 됩니다.
Top comments (0)