API 협업은 무거운 앱을 열고, 동기화를 기다리고, 패널을 클릭하며 팀원이 무엇을 변경했는지 확인하는 것을 의미했습니다. 이제 그럴 필요가 없습니다. API가 OpenAPI 파일로 설명되어 있다면, 대부분의 협업 작업은 실제로는 텍스트 작업입니다: 사양 버전 관리, 차이점 검토, 공유 변경 사항 병합. 이 모든 것은 터미널에서 처리할 수 있습니다.
이 가이드는 세 가지 작업을 처리하는 경량 CLI 도구를 다룹니다. 여기에 있는 모든 도구는 몇 초 만에 설치되고, 단일 명령으로 실행되며, Git 또는 CI에 쉽게 통합됩니다. GUI도, 백그라운드 데몬도, 전체 팀이 변경 로그를 읽기 위해 좌석을 설정할 필요도 없습니다. 팀 워크플로우에 대한 더 자세한 내용은 API 협업 도구에 대한 저희 종합 가이드에서 시작하시고, 이 글은 터미널 우선(terminal-first) 접근 방식의 하위 집합입니다.
여기에 기본 구성이 있습니다. 명령줄에서의 협업은 사양 버전 관리(누가 어떤 버전을 가지고 있는지), 검토(무엇이 변경되었고 안전한지), 그리고 공유 변경 사항(한 사람의 편집 내용을 모든 사람의 신뢰할 수 있는 소스로 병합하는 것)으로 나뉩니다. 아래의 각 도구는 이 중 하나 또는 두 가지를 잘 수행합니다. OpenAPI 사양은 이 도구들이 읽고 쓰는 공식 표준이므로, 모든 것을 작동하게 하는 공유 언어입니다. 여기서는 7가지 도구, 각 도구의 실제 설치 및 예제 명령, 그리고 선택할 수 있는 간략한 표를 제공합니다.
API 협업을 위한 CLI 도구가 "경량"인 이유는 무엇일까요?
'경량'은 단순한 느낌이 아니라 실제 기준입니다. 도구가 다음 기준 대부분을 충족하면 자격이 있습니다.
- 작은 설치. 단일 바이너리,
npx호출, 또는 단 한 번의npm install -g. 설치 프로그램이나 계속 실행해야 할 서비스가 없습니다. - 빠른 시작. 실행되고 바로 종료되므로 스크립트나 pre-commit hook에서 호출할 수 있습니다.
- 낮은 구성. 설정 없이 또는 최소한의 설정으로 일반 OpenAPI 파일에 대해 작동합니다.
openapi.yaml을 가리키고 바로 시작할 수 있습니다. - 터미널 우선. 출력은 웹 패널에서 렌더링되는 것이 아니라 터미널에서 읽거나 CI로 파이프되도록 의도되었습니다.
- 하나의 작업을 잘 수행. 차이점 분석, 게시 또는 병합; 채택해야 할 전체 플랫폼이 아닙니다.
도구들은 대략 가장 작고 가장 집중된 것부터 가장 통합된 것 순서로 나열됩니다. 마지막 항목은 예외인데, 단일 목적의 바이너리라기보다는 완전한 프로젝트 CLI이며, 한 곳에서 버전 관리, 검토 및 병합을 모두 다루기 때문에 포함되었습니다.
Git + 사양 파일 (기본)
가장 가벼운 협업 도구는 이미 가지고 있는 것입니다. OpenAPI 파일을 코드 옆의 저장소에 커밋하면 Git이 버전 관리, 기록 및 검토를 무료로 처리합니다. openapi.yaml에 대한 풀 리퀘스트는 변경된 정확한 라인을 보여주고, 팀원들은 해당 라인에 댓글을 달며, 병합은 공유 변경 사항이 됩니다. 이것이 Git-native API 협업의 전체 아이디어입니다.
# Track the spec in the repo, then review changes like any code
git add openapi.yaml
git commit -m "Add pagination params to GET /orders"
git diff main -- openapi.yaml
가장 적합한 용도: 새로운 도구 없이 기록 및 검토. 모든 개발자가 이미 알고 있습니다.
솔직한 한계: YAML에 대한 원시 Git diff는 노이즈가 많습니다. 키가 재정렬되거나 블록이 재들여쓰기된 경우 API가 동일하더라도 변경으로 보입니다. 이는 다음 도구들이 채워주는 격차입니다: 파일의 텍스트가 아닌 API의 의미를 비교합니다.
oasdiff
oasdiff는 두 OpenAPI 사양을 비교하고 변경 사항이 호환성을 깨뜨리는지 여부를 알려주는 단일 Go 바이너리입니다. 오픈 소스(Apache 2.0)이며 수백 가지의 고유한 변경 유형을 감지하고, 종료 코드를 통해 병합을 쉽게 제어할 수 있습니다. CI에서 실행하면 호환성을 깨뜨리는 변경 사항이 팀원에게 도달하기 전에 빌드를 실패시킵니다.
# Install (macOS)
brew install oasdiff
# Fail the build if the new spec breaks existing clients
oasdiff breaking main-spec.yaml pr-spec.yaml
# exit 0 = safe, exit 1 = breaking changes found
oasdiff changelog base.yaml revision.yaml을 사용하여 변경된 모든 내용을 (호환성을 깨뜨리든 아니든) 사람이 읽기 쉬운 요약으로 확인할 수 있습니다.
가장 적합한 용도: 병합 게이트로서의 호환성 깨는 변경 감지. 빠르고 스크립트화 가능하며 계정이 필요하지 않습니다.
솔직한 한계: 차이점을 비교하고 보고만 합니다. 문서를 게시하거나 브랜치를 관리하지 않습니다. 하나의 명확한 작업을 잘 수행합니다.
Optic
Optic은 Git 워크플로우를 염두에 두고 OpenAPI 변경 사항을 비교하고, 린트하고, 검토하는 npm 설치 CLI입니다. MIT 라이선스이며, 단순한 차이점 분석으로는 놓치기 쉬운 $ref, oneOf, allOf 및 기타 스키마 형태를 이해합니다. oasdiff가 통과/실패 게이트를 제공하는 반면, Optic은 검토 대화에 중점을 둡니다. 이는 작업 중인 사양을 메인 브랜치의 버전과 비교하고 PR에 대한 API 수준 변경 사항을 요약할 수 있습니다.
# Install
npm install -g @useoptic/optic
# Compare the current spec against the one on main
optic diff openapi.yaml --base main --check
가장 적합한 용도: 풀 리퀘스트 내에서 구조화된 변경 사항 검토, 호환성을 깨뜨리거나 금지된 변경 사항으로 간주되는 규칙 포함.
솔직한 한계: Node 기반이므로 단일 Go 바이너리보다 무겁고, 최대한 활용하려면 구성 및 검사 규칙을 채택해야 합니다.
Bump.sh CLI
Bump.sh CLI는 터미널에서 API 문서를 게시하고 비교합니다. 여기서 협업은 공유되고 항상 최신 상태인 문서에 관한 것입니다. 사양이 변경될 때 새로운 버전을 deploy하고, 팀원과 사용자는 동일하게 렌더링된 참조를 읽습니다. diff 명령은 게시된 버전과 로컬 파일 간의 변경 로그를 게시하며, 이는 PR 댓글에 추가하기에 유용합니다. Node 패키지(bump-cli)이며, Node 20+가 필요하며, preview 및 diff는 토큰 없이 작동합니다.
# Install
npm install -g bump-cli
# Publish a new version of the shared docs
bump deploy openapi.yaml --doc my-api --token $BUMP_TOKEN
# Or just get the changelog between versions
bump diff openapi.yaml --doc my-api
가장 적합한 용도: 하나의 공유되고 사람이 읽기 쉬운 문서를 사양과 동기화하고, 검토를 위한 터미널 차이점 분석 제공.
솔직한 한계: 호스팅된 문서 및 배포 흐름은 유료 Bump.sh 제품입니다. CLI는 클라이언트이며, 공유 표면은 그들의 플랫폼에 있습니다.
Redocly CLI
Redocly CLI는 광범위한 OpenAPI 툴킷입니다. OpenAPI 사양을 린트하고, 번들링하며, Redocly 레지스트리(현재 Reunite)로 푸시합니다. push 명령은 협업의 핵심 요소입니다. 사양 버전을 공유 레지스트리에 업로드하여 나머지 조직이 파일을 주고받는 대신 하나의 정식 소스에서 가져오도록 합니다. 번들링도 중요합니다. $ref를 포함하는 다중 파일 사양이 팀원이 사용할 수 있는 하나의 깔끔한 아티팩트가 되기 때문입니다.
# No install needed; run via npx
npx @redocly/cli lint openapi.yaml
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml
# Push a version to the shared registry (needs an API key)
npx @redocly/cli push openapi.yaml --organization "Acme" --project "orders-api"
가장 적합한 용도: 내부 스타일에 맞게 린트하고, 단일 진실 공급원(source-of-truth) 사양을 공유 레지스트리에 푸시.
솔직한 한계: lint 및 bundle은 무료이며 로컬에서 작동하지만, push 및 레지스트리는 Redocly의 호스팅 플랫폼의 일부입니다. 더 심층적인 사양 편집 워크플로우에 대해서는 협업 API 사양 편집에 대한 저희 가이드를 참조하세요.
GitHub CLI (gh)
검토가 풀 리퀘스트에서 이루어진다면, GitHub CLI는 그 전체 흐름을 터미널로 가져옵니다. 브라우저를 열지 않고도 사양을 변경하는 PR을 열고, 검토자를 요청하며, 상태를 확인할 수 있습니다. 이를 oasdiff 또는 Optic과 Git 훅에서 함께 사용하면 사양 검토는 코드 검토의 일반적이고 스크립트 가능한 부분이 됩니다.
# Open a PR for the spec change and tag reviewers
gh pr create --title "Add /orders pagination" --body "Adds page + limit params"
gh pr review --approve
가장 적합한 용도: 팀이 이미 GitHub를 사용하고 있을 때 셸에서 검토 및 병합 대화를 주도.
솔직한 한계: PR을 관리하지만 API의 의미론은 관리하지 않습니다. 변경 사항이 호환성을 깨뜨리는지 알지 못합니다. 이를 위해 oasdiff 또는 Optic을 연결하는 것입니다.
Apidog CLI
Apidog CLI는 여기에서 예외적인 존재입니다. 단일 목적의 바이너리가 아니라, Apidog 플랫폼과 동일한 디자인, 버전 관리 및 협업 데이터에 터미널에서 접근할 수 있는 완전한 프로젝트 리소스 CLI(npm install -g apidog-cli)입니다. 협업을 위해서는 세 가지 명령 그룹이 중요합니다: branch, merge-request, 그리고 git-connection.
Apidog는 오픈 소스가 아닙니다. 무료 티어가 있는 상용 제품입니다. 하지만 diff 도구, 문서 게시자, 레지스트리를 직접 연결하고 싶지 않다면, 무료 티어와 CLI를 통해 사양 브랜치, 검토 흐름, Git 백업을 한 곳에서 얻을 수 있습니다.
독립된 브랜치부터 시작하세요. --type 플래그는 브랜치 모델을 선택합니다: 범위가 지정된 기능 또는 릴리스의 경우 sprint, 진행 중인 작업의 경우 general, 에이전트가 소스를 건드리지 않고 리소스를 편집하는 독립된 브랜치의 경우 ai.
# Install and authenticate
npm install -g apidog-cli
apidog login --with-token $APIDOG_TOKEN
# Start a sprint branch for a shared change
apidog branch create --type sprint --name "orders-pagination"
브랜치가 준비되면 직접 병합하는 대신 병합 요청을 엽니다. 이것이 검토 게이트입니다. 메인이 보호되는 경우, 편집자가 요청을 생성하고 관리자가 승인해야 변경 사항이 적용됩니다. 병합은 명명된 리소스만 선택하므로 공유 변경 사항이 범위 내에 유지됩니다.
# Propose the change for review (safe against a protected main)
apidog merge-request create --branch "orders-pagination" --endpoint-ids 1,2
그리고 git-connection은 각 모듈의 OpenAPI 파일을 Git 저장소(GitHub, GitLab 또는 Azure DevOps 지원)에 백업하므로, 사양이 코드와 함께 버전 제어에 미러링됩니다.
# Wire the project's specs to a Git repo for backup + history
apidog git-connection --help
출력은 agentHints.nextSteps를 포함하는 구조화된 JSON이므로, 스크립트나 AI 에이전트에서 CLI를 쉽게 구동할 수 있습니다. 전체 명령 참조는 Apidog CLI 완전 가이드를 참조하십시오.
가장 적합한 용도: 별도의 도구를 조합할 필요 없이 통합된 버전 관리 + 검토 + 병합 흐름, 그리고 팀과 에이전트를 위해 구축된 브랜치 모델.
솔직한 한계: 플랫폼 CLI이므로 여기에 있는 도구 중 가장 무겁게 설치되며, 로컬 파일이 아닌 Apidog 프로젝트와 통신합니다. 또한 OpenAPI 린터가 없습니다. 스타일 규칙에는 Redocly 또는 Spectral을 사용하세요. 팀에서 브랜치 위에 역할 기반 접근이 필요하다면 RBAC를 통한 안전한 API 협업에 대해 알아보세요.
선택 방법
협업 작업에 맞는 도구를 선택하세요. 그 반대가 아닙니다.
| 도구 | 가장 적합한 용도 | 설치 | 오픈 소스? | 비고 |
|---|---|---|---|---|
| Git + 사양 파일 | 기록 및 검토, 새로운 도구 불필요 | 이미 설치됨 | 예 (Git) | YAML에서 노이즈가 많음; 의미론적 차이점 분석 도구와 함께 사용 |
| oasdiff | 호환성 깨는 변경 병합 게이트 | brew install oasdiff |
예 (Apache 2.0) | 종료 코드가 CI에서 호환성 깨는 변경 발생 시 실패시킴 |
| Optic | PR 내에서 구조화된 변경 검토 | npm i -g @useoptic/optic |
예 (MIT) | $ref, oneOf 등을 이해 |
| Bump.sh CLI | 공유 문서 게시 + 차이점 분석 | npm i -g bump-cli |
CLI는 오픈, 호스팅은 유료 | Node 20+ 필요; diff/preview는 토큰 필요 없음 |
| Redocly CLI | 린트, 번들, 레지스트리에 푸시 | 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 |
대부분의 팀은 여러 도구를 조합하여 사용합니다. 일반적인 경량 스택은 다음과 같습니다: 사양을 Git에 커밋하고, oasdiff 또는 Optic을 병합 게이트로 실행하며, Bump.sh 또는 Redocly로 게시합니다. 하나의 CLI에서 브랜치 관리, 검토 및 병합을 실행하고 싶다면, Apidog가 이 세 가지를 모두 다룹니다. 스택 선택에 대한 더 광범위한 정보는 API 협업 팀 도구 가이드에서 옵션을 비교해 보세요.
마무리
터미널에서의 협업은 세 가지 단계로 이루어집니다: 사양 버전 관리, 차이점 검토, 공유 변경 사항 병합. Git이 첫 번째를 처리하고, oasdiff 및 Optic이 두 번째를 개선하며, Bump.sh 및 Redocly가 결과를 게시하고, gh가 PR을 주도합니다. Apidog CLI는 팀과 에이전트 모두를 위해 구축된 브랜치 모델을 통해 버전 관리, 검토 및 병합을 하나의 명령 집합으로 통합합니다.
도구들을 직접 연결하지 않고 통합된 경로를 원하십니까? Apidog를 다운로드하고, apidog-cli를 설치한 다음, 현재 작업 중인 터미널에서 첫 번째 apidog branch create 및 merge-request를 실행하세요. 거기서 CLI를 CI에 연결하는 것은 간단한 다음 단계입니다.