API 디자인은 코드가 배포되기 훨씬 전에 사양 파일에서 이루어집니다. 잊어버린 스타일 규칙, 놓친 주요 변경 사항, 지난주에 배포한 것과 달라진 스키마 등 이 모든 것은 나중에 수정하려면 더 많은 비용이 듭니다. 명령줄은 이러한 문제가 시작되는 곳에서 문제를 포착하며, 누구도 UI를 클릭할 필요 없이 CI에서 이를 수행합니다.
이 글은 해당 도구 체인의 오픈 소스 측면에 대한 것입니다. 여기에 있는 모든 도구는 허용적 라이선스 하에 소스 이용이 가능하며, 추가 비용 없이 무료로 실행할 수 있고, 자체 호스팅하거나 제어하는 버전으로 고정할 수 있습니다. API 디자인이 Git 저장소에 있고 모든 랩톱과 모든 파이프라인에서 동일한 방식으로 검사를 실행하고 싶을 때 이것은 중요합니다. 이 모든 것이 어떻게 어우러지는지에 대한 더 넓은 그림을 원한다면, API 설계 방법에 대한 저희 가이드부터 시작하고, 그 다음에 여기로 돌아와 CLI를 선택하세요.
여러분은 여섯 가지 도구를 얻게 될 것이며, 각 도구에는 실제 설치 명령어와 작동 방식을 보여주는 하나의 명령어가 있습니다: 스타일 규칙을 위한 린터, 그에 대한 빠른 Go 기반 대안, 유효성 검사도 하는 번들러, 코드 및 문서 생성기, 그리고 사양 버전 간의 주요 변경 사항을 감지하는 두 가지 도구입니다. OpenAPI Specification은 이 모든 도구가 공통으로 사용하는 언어이므로, 한 도구로 린트한 사양은 다음 도구로 깔끔하게 전달됩니다.
솔직한 한 가지 말씀드립니다. 여기에 Apidog가 소개되어 있지만, 오픈 소스는 아닙니다. 무료 티어가 있는 상업용 제품이며, 여러분의 사양을 린트하지 않습니다. 따라서 오픈 소스 목록이 아닌 정확한 보충 설명으로 포함됩니다. 아래 도구들이 진정한 오픈 소스 디자인 도구 체인입니다.
API 디자인을 위한 CLI 도구가 오픈 소스인 조건
오픈 소스는 분위기가 아닌 구체적인 주장입니다. 이 목록에서는 다음 세 가지가 참일 때 도구가 자격을 얻습니다.
첫째, 라이선스입니다. 읽을 수 있는 실제 허용적이거나 카피레프트 라이선스여야 합니다. 여기서는 MIT와 Apache-2.0이 가장 많이 보일 것입니다. 이것이 여러분이 라이선스 비용이나 사용자 수 제한 없이 상업 프로젝트에서 도구를 사용할 수 있게 해줍니다.
둘째, 자체 호스팅 및 버전 관리입니다. 바이너리를 벤더링하고, 정확한 버전을 고정하며, 에어 갭(air-gapped) CI 러너에서 완전히 오프라인으로 실행할 수 있습니다. 여기에 있는 어떤 도구도 핵심 작업을 수행하기 위해 외부와 통신하거나 계정이 필요하지 않습니다.
셋째, 유지보수 및 커뮤니티입니다. 최근 커밋이 있고, 답변이 달리는 공개 이슈가 있으며, 공개 변경 로그가 있는 저장소여야 합니다. 방치된 프로젝트는 MIT 라이선스일지라도 여전히 나쁜 선택일 수 있으므로, 유지보수 상태가 중요한 곳에 표시합니다.
아래의 모든 도구는 이 세 가지 기준에 따라 검토됩니다. 프로젝트가 정체 상태에 있는 경우, 해당 내용이 언급될 것입니다.
Spectral: 유연한 OpenAPI 스타일 린터
Stoplight의 Spectral은 API 설명서를 위한 레퍼런스 오픈 소스 린터이며, Apache-2.0 라이선스 하에 제공됩니다. 이 도구는 규칙 세트(규칙을 나열하는 YAML, JSON 또는 JavaScript 파일)를 읽고 OpenAPI 3.x, OpenAPI 2.0, AsyncAPI 및 Arazzo 문서에 적용합니다. 팀에 작성된 API 스타일 가이드가 있다면, Spectral을 통해 이를 실행 가능하게 만들 수 있습니다.
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
기본적으로 이 도구는 누락된 설명, 유효하지 않은 예시, 구조적 문제를 표시하는 oas 규칙 세트를 제공합니다. 진정한 가치는 사용자 정의 규칙에서 나타납니다: 모든 작업에 operationId를 요구하고, 오류 응답에 공유 스키마를 적용하며, 경로에 명명 규칙을 적용하는 등입니다. 이러한 규칙은 저장소에 존재하며 모든 기여자에게 동일하게 실행됩니다.
가장 적합한 용도: 팀 스타일 가이드를 코드로 강제하는 것. 솔직한 한계: Spectral은 단일 사양만 검사합니다. 두 가지 버전을 비교하지 않으므로, 주요 변경 사항을 감지하려면 diff 도구와 함께 사용해야 합니다.
vacuum: 가장 빠른 린터, Spectral 규칙 세트를 위한 드롭인 대체
Spectral이 표준이라면, vacuum은 속도에 중점을 둡니다. 이는 MIT 라이선스를 가진 Go 린터로, Spectral 규칙 세트와 100% 호환됩니다. 따라서 이미 작성한 동일한 규칙 세트를 사용하여 대규모 사양에서 훨씬 빠르게 결과를 얻을 수 있으며, 이는 사전 커밋 훅 또는 긴밀한 CI 루프에서 원하는 바입니다.
brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml
-d 플래그는 규칙별 상세 출력을 제공합니다. vacuum은 린트 기능 이상을 수행합니다. 동일한 사양에서 HTML 보고서와 문서를 생성합니다. Node 런타임이 없는 단일 컴파일된 바이너리이므로 빠르게 시작하고 컨테이너에 깔끔하게 통합됩니다.
가장 적합한 용도: 이미 가지고 있는 규칙 세트로 대규모 사양을 빠르게 린트하는 것. 솔직한 한계: 규칙 세트 생태계와 문서는 여전히 Spectral을 중심으로 하기 때문에, 여러분은 종종 Spectral 모델에 맞춰 규칙을 작성하고 vacuum을 통해 실행하게 됩니다. 이는 기능이지만, Spectral을 먼저 배워야 한다는 의미입니다.
Redocly CLI: 하나의 바이너리로 린트 및 번들링
Redocly CLI는 MIT 라이선스를 가지며 약간 다른 작업을 다룹니다. 린트 기능을 제공하지만, 가장 뛰어난 기능은 bundle입니다. 이 기능은 여러 $ref 파일로 분할된 사양(대규모 API 디자인을 유지보수 가능하게 하는 합리적인 방법)을 가져와 단일 파일을 기대하는 도구를 위해 하나의 문서로 평탄화합니다. 또한 번들된 결과에서 API 참조 문서를 생성합니다.
npm install -g @redocly/cli
redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml
사양을 리소스별 파일로 분할하면 차이점을 읽기 쉽게 유지하고 병합 충돌을 줄일 수 있으며, 이는 Git-native API 디자인 워크플로우의 핵심입니다. Redocly의 bundle은 여러 파일로 된 소스를 CI, 목 서버 또는 문서 사이트가 사용하는 단일 아티팩트로 다시 변환하는 단계입니다.
가장 적합한 용도: 번들링과 유효성 검사가 필요한 다중 파일 사양 프로젝트. 솔직한 한계: 기본 린트 규칙이 전체 사용자 정의 Spectral 규칙 세트보다 가볍기 때문에, 많은 팀은 번들링을 위해 Redocly를 사용하고 심층적인 스타일 적용을 위해 Spectral 또는 vacuum을 사용합니다.
openapi-generator: 디자인을 클라이언트, 스텁 및 문서로 변환
다른 사람들이 그것을 기반으로 빌드할 수 있을 때까지 디자인은 완성된 것이 아닙니다. openapi-generator는 Apache-2.0 라이선스를 가지며, OpenAPI 사양으로부터 수십 가지 언어로 클라이언트 SDK, 서버 스텁 및 문서를 생성합니다. 사양을 진실의 원천으로 취급하고 나머지를 생성하는 것은 API 디자인 원칙에서 다루는 스키마 우선, 계약 중심 접근 방식의 핵심입니다.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
-g typescript-axios를 go, python, java, kotlin 또는 지원되는 여러 생성기 중 하나로 바꿀 수 있습니다. 모든 사양 변경 시 CI에서 실행하면 클라이언트 라이브러리가 계약에서 벗어나지 않습니다.
가장 적합한 용도: 생성된 코드와 문서를 디자인과 일치시키는 것. 솔직한 한계: 실행하려면 JDK(JDK 11 이상)가 필요하고, 생성된 코드는 종종 사용자 정의해야 하는 시작점이며, 생성기 품질은 언어 대상에 따라 다릅니다. 배포하기 전에 출력을 확인하세요.
oasdiff: 주요 변경 사항이 클라이언트에 도달하기 전에 감지
린터는 하나의 사양이 깔끔한지 알려줍니다. 하지만 필드 이름을 변경하는 것이 프로덕션의 모든 클라이언트를 망가뜨렸다는 것은 알려주지 못합니다. oasdiff는 Apache-2.0 Go 도구로, 이 간극을 메워줍니다. 사양의 두 가지 버전을 제공하면 차이점, 특히 주요 변경 사항을 보고합니다.
go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml
breaking 명령어는 기존 소비자를 망가뜨리는 변경 사항만 보여줍니다. changelog는 주요 변경 사항이든 아니든 모든 변경 사항에 대한 사람이 읽을 수 있는 목록을 제공합니다. diff는 전체 기계가 읽을 수 있는 차이점을 제공합니다. oasdiff breaking을 풀 리퀘스트 검사에 연결하면, 주요 변경 사항은 새벽 3시의 호출 대신 빌드 실패로 바뀝니다.
가장 적합한 용도: CI에서 주요 변경 사항을 게이팅(gating)하는 것. 솔직한 한계: 사양을 비교하므로, 실제 API와 사양을 최신 상태로 유지하는 여러분의 규율만큼만 좋습니다. 스타일 린트 기능은 없습니다. Spectral 또는 vacuum과 함께 사용하세요.
Optic: diff와 린트 동시 수행, 유지보수 주의사항
Optic은 MIT 라이선스를 가지며, 다른 도구들이 분리해서 하는 작업을 하나로 합칩니다. 하나의 도구에서 OpenAPI를 린트하고 diff하며, 두 버전을 비교하여 주요 변경 사항을 표시하고 스타일 규칙도 적용합니다. 관찰된 테스트 트래픽으로부터 사양을 생성할 수도 있습니다.
npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check
오픈 소스 목록이 여러분에게 제공해야 할 솔직한 정보가 있습니다. Optic의 공개 저장소는 2026년 초에 아카이브되었고, 이 프로젝트는 더 이상 적극적으로 유지보수되지 않습니다. MIT 소스는 여전히 실행되므로 벤더링할 수 있지만, 새로운 규칙이나 보안 패치를 받을 수는 없을 것입니다. 오늘날 주요 변경 사항 감지를 위해서는 oasdiff가 유지보수되는 옵션입니다. Optic은 기존 파이프라인에서 여전히 발견될 수 있으므로 목록에 남아 있습니다.
가장 적합한 용도: 이미 투자한 팀, 또는 하나의 CLI에서 린트와 diff를 모두 원하는 사람. 솔직한 한계: 2026년 초부터 더 이상 유지보수되지 않습니다. 레거시로 취급하고 마이그레이션 경로를 계획하세요.
Apidog가 적합한 곳 (그리고 적합하지 않은 곳)
Apidog는 오픈 소스가 아니며, OpenAPI를 린트하거나 스타일 규칙을 강제하지 않습니다. Spectral, vacuum, Redocly가 여러분의 린터입니다, 그 이상도 이하도 아닙니다. Apidog가 제공하는 것은 다른 트레이드오프입니다. 여섯 개의 개별 바이너리를 함께 연결하는 대신, 무료 티어와 apidog-cli 바이너리를 통해 엔드포인트와 데이터 스키마를 설계할 통합된 공간을 제공하며, 그 결과를 OpenAPI로 내보내 이러한 오픈 소스 검사에 바로 사용할 수 있습니다.
npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml
CLI는 endpoint, schema, mock, 그리고 import/export를 위한 명령 그룹을 가지고 있어서, 터미널에서 API 디자인을 스크립트하고 내보낸 사양을 openapi-generator나 oasdiff에 전달할 수 있습니다. 전체 명령어 세트는 Apidog CLI 완전 가이드를 참조하세요. 솔직히 말해서: Apidog는 오픈 소스 도구 체인과 잘 어울리는 상업적 통합 옵션이며, 린터를 대체하거나 그 자체가 오픈 소스 프로젝트는 아닙니다.
선택 방법
작업에 맞는 도구를 선택하세요. 대부분의 팀은 이 도구들 중 하나만 사용하는 것이 아니라 두세 개를 함께 사용합니다.
| 도구 | 가장 적합한 용도 | 설치 | 오픈 소스? | 비고 |
|---|---|---|---|---|
| Spectral | 스타일 가이드 린팅 | npm i -g @stoplight/spectral-cli |
예 (Apache-2.0) | 레퍼런스 린터; 사용자 정의 규칙 작성 |
| vacuum | 대규모 고속 린팅 | brew install --cask daveshanley/vacuum/vacuum |
예 (MIT) | Spectral 규칙 세트 실행, Go 기반으로 빠름 |
| Redocly CLI | 번들링 + 유효성 검사 | npm i -g @redocly/cli |
예 (MIT) | 다중 파일 $ref 사양에 최적 |
| openapi-generator | SDK / 스텁 / 문서 생성 | npm i -g @openapitools/openapi-generator-cli |
예 (Apache-2.0) | JDK 11+ 필요 |
| oasdiff | 주요 변경 사항 감지 | go install github.com/oasdiff/oasdiff@latest |
예 (Apache-2.0) | 유지보수 중; PR 검사에 사용 |
| Optic | 린트 + diff 동시 수행 | npm i -g @useoptic/optic |
예 (MIT) | 2026년 초 저장소 아카이브됨; 레거시 |
| Apidog CLI | 통합 디자인 + 내보내기 | npm i -g apidog-cli |
아니요 (무료 티어) | 린터 아님; OpenAPI 내보내기 |
실용적인 스택: 스타일에는 Spectral 또는 vacuum, 번들링에는 Redocly, 주요 변경 사항에는 oasdiff, 클라이언트 생성을 위해서는 openapi-generator를 사용합니다. 이렇게 많은 도구를 유지보수하는 것이 부담스럽다면, 통합 플랫폼이 디자인 및 내보내기 부분을 한 곳에서 처리합니다. CLI를 넘어선 도구 환경에 대한 더 넓은 관점을 원하시면, API 디자인 및 테스트를 위한 Swagger 대안에 대한 저희 가이드와 REST API 디자인 방법의 기본 사항을 참조하세요.
마무리
API 디자인을 위한 오픈 소스 CLI 도구 체인은 성숙하고 무료로 실행할 수 있습니다. Spectral과 vacuum은 린트 기능을, Redocly는 번들링을, openapi-generator는 클라이언트를 생성하며, oasdiff는 주요 변경 사항을 방지하고 Optic은 레거시 옵션으로 인식됩니다. 이들을 CI에 연결하면 푸시할 때마다 API 계약이 확인되며, 사용자별 비용이나 벤더 종속 없이 사용할 수 있습니다.
만약 하나의 통합 도구에서 엔드포인트와 스키마를 설계하고 깔끔한 OpenAPI를 동일한 파이프라인으로 내보내고 싶다면, Apidog를 다운로드하여 apidog-cli를 사용해보세요. 이는 오픈 소스 스택의 상업적 동반자이지, 린터를 대체하는 것은 아닙니다. 어떤 방법을 사용하든 목표는 동일합니다. 사용자가 도달하기 전에 터미널에서 디자인 문제를 감지하는 것입니다.