DEV Community

Cover image for API 협업을 위한 최고의 경량 CLI 도구
Rihpig
Rihpig

Posted on • Originally published at apidog.com

API 협업을 위한 최고의 경량 CLI 도구

API 협업은 더 이상 무거운 앱을 열고 동기화를 기다리며 패널을 클릭하는 작업일 필요가 없습니다. OpenAPI 파일로 API를 정의했다면, 대부분의 협업은 텍스트 기반 작업으로 처리할 수 있습니다. 즉, 사양 버전을 관리하고, 변경 사항을 검토하고, 승인된 변경을 병합하는 흐름입니다. 이 작업은 모두 터미널과 Git, CI에서 실행할 수 있습니다.

지금 Apidog 사용해 보기

이 글에서는 API 협업에 바로 적용할 수 있는 경량 CLI 도구 7가지를 다룹니다. 각 도구는 빠르게 설치할 수 있고, 단일 명령으로 실행되며, Git hook 또는 CI 파이프라인에 연결하기 쉽습니다. 팀 워크플로우 전반이 필요하다면 API 협업 도구 가이드도 함께 참고하세요. 이 글은 그중 터미널 우선(terminal-first) 워크플로우에 집중합니다.

CLI 기반 협업은 다음 세 작업으로 나눌 수 있습니다.

  1. 사양 버전 관리: 누가 어떤 OpenAPI 버전을 사용하는지 추적
  2. 변경 검토: 무엇이 변경됐고 호환성을 깨뜨리는지 확인
  3. 공유 변경 병합: 검토된 변경을 팀의 신뢰할 수 있는 소스로 반영

OpenAPI는 이 도구들이 읽고 쓰는 공식 표준입니다. 따라서 팀이 같은 OpenAPI 파일을 기준으로 작업하면 도구가 달라도 협업 흐름을 유지할 수 있습니다.

API 협업용 CLI 도구가 경량인 기준

경량 도구는 단순히 설치 파일이 작다는 뜻이 아닙니다. 다음 조건을 대부분 충족해야 팀 워크플로우에 부담 없이 추가할 수 있습니다.

  • 작은 설치 범위: 단일 바이너리, npx, 또는 한 번의 npm install -g로 설치할 수 있습니다.
  • 빠른 실행: 실행 후 바로 종료되므로 CI, shell script, pre-commit hook에서 호출할 수 있습니다.
  • 낮은 구성 비용: 별도 설정 없이 openapi.yaml 같은 일반 OpenAPI 파일을 바로 처리합니다.
  • 터미널 우선 출력: 결과를 터미널에서 읽거나 CI 로그와 PR 댓글로 전달할 수 있습니다.
  • 명확한 단일 역할: diff, lint, publish, merge 등 한두 가지 작업에 집중합니다.

아래 도구는 가장 단순한 Git 기반 방식부터 통합형 프로젝트 CLI까지 순서대로 정리했습니다.

1. Git + OpenAPI 사양 파일

가장 먼저 도입할 도구는 이미 사용 중인 Git입니다. OpenAPI 파일을 애플리케이션 코드와 같은 저장소에 커밋하면 Git이 버전 관리, 변경 기록, PR 기반 검토를 처리합니다.

# OpenAPI 사양을 코드와 함께 추적
git add openapi.yaml
git commit -m "Add pagination params to GET /orders"

# main 브랜치와 현재 사양의 텍스트 차이 확인
git diff main -- openapi.yaml
Enter fullscreen mode Exit fullscreen mode

PR에서 openapi.yaml을 변경하면 팀원은 수정된 줄에 직접 댓글을 남기고, 승인 후 병합할 수 있습니다. 이것이 Git-native API 협업의 기본입니다.

가장 적합한 용도: 새 도구를 추가하지 않고 API 사양의 이력과 검토를 시작할 때

한계: Git diff는 YAML의 텍스트 차이를 보여줍니다. 키 순서 변경이나 들여쓰기 수정도 API 변경처럼 보일 수 있습니다. 실제 API 의미론과 호환성은 다음 도구로 검사하는 편이 좋습니다.

2. oasdiff

oasdiff는 두 OpenAPI 사양을 비교하고, 새 버전이 기존 클라이언트와의 호환성을 깨뜨리는지 검사하는 Go 기반 CLI입니다. 종료 코드를 제공하므로 CI 병합 게이트로 사용하기 좋습니다.

# macOS 설치
brew install oasdiff

# 호환성을 깨는 변경이 있으면 실패
oasdiff breaking main-spec.yaml pr-spec.yaml

# exit 0: 호환성 문제 없음
# exit 1: 호환성을 깨는 변경 발견
Enter fullscreen mode Exit fullscreen mode

변경 내역 전체를 사람이 읽기 쉬운 형식으로 확인하려면 changelog를 사용합니다.

oasdiff changelog main-spec.yaml pr-spec.yaml
Enter fullscreen mode Exit fullscreen mode

GitHub Actions 같은 CI에서 다음과 같이 연결할 수 있습니다.

- name: Check breaking OpenAPI changes
  run: oasdiff breaking main-spec.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

가장 적합한 용도: 호환성을 깨는 변경을 병합 전에 차단하는 CI 게이트

한계: diff와 보고에 집중합니다. 문서 게시, 브랜치 관리, 병합 요청 관리는 처리하지 않습니다.

3. Optic

Optic은 Git 워크플로우에 맞춰 OpenAPI 변경을 비교, 린트, 검토하는 npm 기반 CLI입니다. 단순한 텍스트 비교와 달리 $ref, oneOf, allOf 같은 스키마 구조를 이해합니다.

# 설치
npm install -g @useoptic/optic

# 현재 사양을 main 기준으로 비교하고 검사
optic diff openapi.yaml --base main --check
Enter fullscreen mode Exit fullscreen mode

PR 워크플로우에서는 다음 순서로 사용합니다.

  1. 기능 브랜치에서 openapi.yaml 수정
  2. optic diff로 main 브랜치와 비교
  3. 검사 결과를 CI 로그 또는 PR 체크로 노출
  4. 검토 후 병합

가장 적합한 용도: PR에서 API 수준의 구조화된 변경 사항을 검토할 때

한계: Node 기반 도구이므로 단일 Go 바이너리보다 설치 범위가 큽니다. 검사 규칙과 구성을 정의할수록 활용도가 높아집니다.

4. Bump.sh CLI

Bump.sh CLI는 터미널에서 API 문서를 게시하고 사양 간 변경을 비교하는 도구입니다. 팀 협업에서 “모두가 같은 최신 API 문서를 본다”는 요구가 있을 때 유용합니다.

# 설치
npm install -g bump-cli

# 공유 문서의 새 버전 배포
bump deploy openapi.yaml --doc my-api --token $BUMP_TOKEN

# 로컬 사양과 게시된 문서의 변경 내역 확인
bump diff openapi.yaml --doc my-api
Enter fullscreen mode Exit fullscreen mode

diff 결과는 PR 댓글이나 CI 로그에 추가할 수 있습니다. 문서 배포 전 변경 사항을 검토하는 용도로도 사용할 수 있습니다.

가장 적합한 용도: 공유 API 문서를 최신 사양과 동기화하고, 사람이 읽기 쉬운 변경 내역을 제공할 때

한계: 호스팅 문서 및 배포 흐름은 유료 Bump.sh 플랫폼과 연결됩니다. CLI는 해당 플랫폼을 위한 클라이언트 역할을 합니다. Node 20+가 필요하며, preview와 diff는 토큰 없이 실행할 수 있습니다.

5. Redocly CLI

Redocly CLI는 OpenAPI 사양의 lint, bundle, 레지스트리 업로드를 처리하는 도구입니다. 여러 파일로 분리된 사양을 하나의 배포 가능한 OpenAPI 파일로 만들고 싶을 때 특히 유용합니다.

# 설치 없이 npx로 실행
npx @redocly/cli lint openapi.yaml

# 여러 파일과 $ref를 하나의 사양 파일로 번들링
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml

# 공유 레지스트리에 사양 업로드
npx @redocly/cli push openapi.yaml --organization "Acme" --project "orders-api"
Enter fullscreen mode Exit fullscreen mode

팀에서 사용할 기본 흐름은 다음과 같습니다.

# 1. 스타일 및 구조 검사
npx @redocly/cli lint openapi.yaml

# 2. 배포/공유용 단일 파일 생성
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml

# 3. 검토 후 레지스트리에 업로드
npx @redocly/cli push dist/openapi.yaml --organization "Acme" --project "orders-api"
Enter fullscreen mode Exit fullscreen mode

가장 적합한 용도: OpenAPI 스타일 규칙을 검사하고, 다중 파일 사양을 번들링하며, 공유 레지스트리를 정식 소스로 운영할 때

한계: lint와 bundle은 로컬에서 사용할 수 있지만, push와 레지스트리는 Redocly 호스팅 플랫폼에 속합니다. 더 깊은 사양 편집 워크플로우는 협업 API 사양 편집 가이드도 참고하세요.

6. GitHub CLI (gh)

검토와 병합이 GitHub PR에서 이루어진다면 GitHub CLI를 사용해 브라우저 없이 전체 PR 흐름을 처리할 수 있습니다.

# API 사양 변경 PR 생성
gh pr create \
  --title "Add /orders pagination" \
  --body "Adds page + limit params"

# 현재 PR 승인
gh pr review --approve
Enter fullscreen mode Exit fullscreen mode

gh는 oasdiff나 Optic과 함께 쓸 때 가장 효과적입니다. 예를 들어 CI에서 호환성 검사를 실행하고, gh로 PR 상태와 리뷰를 관리할 수 있습니다.

# 현재 브랜치의 PR 상태 확인
gh pr status

# PR 검사 결과 확인
gh pr checks
Enter fullscreen mode Exit fullscreen mode

가장 적합한 용도: GitHub를 이미 사용하는 팀에서 셸 기반으로 PR 검토와 병합 흐름을 운영할 때

한계: PR은 관리하지만 API 의미론은 분석하지 않습니다. 호환성 검사는 oasdiff 또는 Optic 같은 도구를 추가해야 합니다.

7. Apidog CLI

Apidog CLI는 단일 목적의 diff 도구와 달리, Apidog 프로젝트의 디자인, 버전 관리, 검토, 병합 데이터를 터미널에서 다루는 프로젝트 리소스 CLI입니다.

협업에서 주로 사용하는 명령 그룹은 다음 세 가지입니다.

  • branch
  • merge-request
  • git-connection 
# 설치 및 인증
npm install -g apidog-cli
apidog login --with-token $APIDOG_TOKEN

# 공유 변경을 위한 sprint 브랜치 생성
apidog branch create --type sprint --name "orders-pagination"
Enter fullscreen mode Exit fullscreen mode

--type으로 브랜치 모델을 선택할 수 있습니다.

  • sprint: 범위가 명확한 기능 또는 릴리스 작업
  • general: 지속적인 일반 작업
  • ai: 에이전트가 소스를 직접 수정하지 않고 리소스를 편집하는 독립 브랜치

브랜치 작업이 끝나면 main에 직접 반영하는 대신 병합 요청을 생성합니다.

# 보호된 main 브랜치에 안전하게 변경 제안
apidog merge-request create \
  --branch "orders-pagination" \
  --endpoint-ids 1,2
Enter fullscreen mode Exit fullscreen mode

git-connection을 사용하면 각 모듈의 OpenAPI 파일을 GitHub, GitLab 또는 Azure DevOps 저장소에 백업할 수 있습니다.

# Git 연결 관련 명령 확인
apidog git-connection --help
Enter fullscreen mode Exit fullscreen mode

CLI 출력은 agentHints.nextSteps를 포함하는 구조화된 JSON이므로 shell script나 AI 에이전트에서 후속 작업을 자동화하기 쉽습니다. 전체 명령은 Apidog CLI 완전 가이드를 참고하세요.

가장 적합한 용도: 여러 도구를 조합하지 않고 브랜치, 검토, 병합 흐름을 하나의 CLI에서 처리할 때

한계: 로컬 OpenAPI 파일만 다루는 도구가 아니라 Apidog 프로젝트와 통신하는 플랫폼 CLI입니다. 이 글의 도구 중 설치 범위가 가장 크며, OpenAPI lint 기능은 제공하지 않습니다. 스타일 규칙 검사는 Redocly 또는 Spectral을 함께 사용하세요. 역할 기반 접근 제어가 필요하다면 RBAC를 통한 안전한 API 협업도 참고할 수 있습니다.

선택 방법

도구를 먼저 정하지 말고, 현재 필요한 협업 작업부터 정하세요.

도구 가장 적합한 용도 설치 오픈 소스? 비고
Git + 사양 파일 이력 및 검토, 새 도구 불필요 이미 설치됨 예 (Git) YAML diff가 노이즈를 만들 수 있으므로 의미론적 diff 도구와 함께 사용
oasdiff 호환성을 깨는 변경의 병합 게이트 brew install oasdiff 예 (Apache 2.0) 종료 코드로 CI에서 실패 처리 가능
Optic PR 내 구조화된 변경 검토 npm i -g @useoptic/optic 예 (MIT) $ref, oneOf, allOf 등 스키마 구조 이해
Bump.sh CLI 공유 문서 게시 및 diff npm i -g bump-cli CLI는 오픈, 호스팅은 유료 Node 20+ 필요, diff/preview는 토큰 불필요
Redocly CLI lint, bundle, 레지스트리 업로드 npx @redocly/cli CLI는 오픈, 레지스트리는 유료 push에 API 키 필요
GitHub CLI 셸에서 PR 검토 주도 brew install gh 예 (MIT) PR 관리용이며 API 의미론 분석은 하지 않음
Apidog CLI 통합된 버전 관리, 검토, 병합 npm i -g apidog-cli 아니요 (무료 티어 제공) branch / merge-request / git-connection 제공

대부분의 팀은 도구를 조합해 사용합니다. 가장 단순한 실전 스택은 다음과 같습니다.

# 1. 사양을 Git에 커밋
git add openapi.yaml
git commit -m "Update orders API"

# 2. 호환성을 깨는 변경 차단
oasdiff breaking main-spec.yaml openapi.yaml

# 3. 사양 품질 검사 및 배포용 번들 생성
npx @redocly/cli lint openapi.yaml
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

공유 문서를 운영해야 한다면 Bump.sh 또는 Redocly를 추가하세요. 브랜치, 검토, 병합을 하나의 CLI에서 관리하려면 Apidog를 사용할 수 있습니다. 더 넓은 도구 선택 기준은 API 협업 팀 도구 가이드에서 비교할 수 있습니다.

마무리

터미널 기반 API 협업은 다음 세 단계로 정리할 수 있습니다.

  1. Git으로 OpenAPI 사양을 버전 관리합니다.
  2. oasdiff 또는 Optic으로 변경 의미와 호환성을 검토합니다.
  3. GitHub PR, Redocly, Bump.sh, 또는 Apidog 흐름으로 공유 변경을 승인·게시·병합합니다.

Apidog CLI는 브랜치 모델과 병합 요청을 통해 버전 관리, 검토, 병합을 하나의 명령 집합으로 통합합니다.

통합된 워크플로우가 필요하다면 Apidog를 다운로드하고 apidog-cli를 설치한 뒤, 현재 터미널에서 첫 번째 apidog branch create와 merge-request를 실행해 보세요. 이후 CI 연결은 자연스러운 다음 단계입니다.

Top comments (0)