DEV Community

Cover image for 무료 오픈소스 API 설계 CLI 도구
Rihpig
Rihpig

Posted on • Originally published at apidog.com

무료 오픈소스 API 설계 CLI 도구

API 디자인 문제는 코드가 배포되기 전에 사양 파일에서 시작됩니다. 누락된 스타일 규칙, 놓친 주요 변경 사항, 지난 배포와 달라진 스키마는 모두 나중에 수정할수록 비용이 커집니다. CLI 도구를 사용하면 개발자 로컬 환경과 CI에서 UI 클릭 없이 이러한 문제를 조기에 잡을 수 있습니다.

지금 Apidog 사용해 보기

이 글에서는 OpenAPI 기반 API 디자인 워크플로우에 적용할 수 있는 오픈 소스 CLI 도구를 다룹니다. 모든 도구는 허용적 라이선스 하에 소스를 사용할 수 있고, 추가 비용 없이 실행하며, 자체 호스팅하거나 특정 버전으로 고정할 수 있습니다. API 디자인을 Git 저장소에서 관리하고 모든 랩톱 및 CI 파이프라인에서 동일한 검사를 실행하려면 이런 특성이 중요합니다.

전체 API 설계 흐름이 필요하다면 먼저 API 설계 방법을 참고한 뒤, 이 글에서 필요한 CLI를 선택하세요.

이 글에서 다루는 도구는 다음과 같습니다.

  • 스타일 규칙을 적용하는 린터: Spectral, vacuum
  • 린트와 번들링을 처리하는 도구: Redocly CLI
  • SDK, 서버 스텁, 문서를 생성하는 도구: openapi-generator
  • 주요 변경 사항을 감지하는 도구: oasdiff, Optic
  • OpenAPI를 내보내는 통합 디자인 옵션: Apidog CLI

OpenAPI Specification은 이 도구들이 공유하는 형식입니다. 한 도구로 린트한 사양을 다음 도구의 입력으로 그대로 전달할 수 있습니다.

참고: 이 글에 포함된 Apidog는 오픈 소스 도구가 아닙니다. 무료 티어가 있는 상업용 제품이며 OpenAPI 스타일 린팅을 수행하지 않습니다. 따라서 오픈 소스 도구 목록의 대체재가 아니라, OpenAPI를 설계하고 내보내는 보완 옵션으로 다룹니다.

API 디자인 CLI 도구가 오픈 소스여야 하는 조건

이 글에서는 다음 세 조건을 만족할 때 오픈 소스 도구로 분류합니다.

  1. 명확한 라이선스

    MIT, Apache-2.0처럼 확인 가능한 라이선스가 있어야 합니다. 이를 통해 라이선스 비용이나 사용자 수 제한 없이 상업 프로젝트에서도 도구를 사용할 수 있습니다.

  2. 자체 호스팅 및 버전 고정 가능 여부

    바이너리를 벤더링하고, 특정 버전을 고정하며, 에어 갭(air-gapped) CI 러너에서도 오프라인으로 실행할 수 있어야 합니다. 핵심 검사를 위해 계정이나 외부 서비스 통신이 필요하면 안 됩니다.

  3. 유지보수 상태와 커뮤니티

    최근 커밋, 공개 이슈, 변경 로그를 확인할 수 있어야 합니다. MIT 라이선스라고 해도 장기간 방치된 프로젝트는 운영 환경에서 위험할 수 있습니다.

아래 도구는 이 기준을 기준으로 정리합니다. 유지보수 상태에 주의할 점이 있는 경우 함께 표시합니다.

Spectral: OpenAPI 스타일 가이드를 코드로 강제하기

Stoplight의 Spectral은 Apache-2.0 라이선스의 OpenAPI 린터입니다. YAML, JSON 또는 JavaScript로 작성한 규칙 세트를 OpenAPI 3.x, OpenAPI 2.0, AsyncAPI, Arazzo 문서에 적용할 수 있습니다.

설치 후 기본 린트를 실행합니다.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

기본 oas 규칙 세트는 다음과 같은 문제를 검사합니다.

  • 누락된 설명
  • 잘못된 예시 값
  • 구조적 오류
  • OpenAPI 규격 위반

팀 스타일 가이드가 있다면 .spectral.yaml에 규칙으로 정의하세요.

extends:
  - spectral:oas

rules:
  require-operation-id:
    description: 모든 operation은 operationId를 가져야 합니다.
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy

  kebab-case-paths:
    description: 경로는 kebab-case를 사용합니다.
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: '^/[a-z0-9-/{}/]+$'
Enter fullscreen mode Exit fullscreen mode

이제 저장소 루트에서 규칙과 사양을 함께 관리할 수 있습니다.

spectral lint openapi.yaml --ruleset .spectral.yaml
Enter fullscreen mode Exit fullscreen mode

가장 적합한 용도: 팀의 API 스타일 가이드를 코드로 강제할 때

한계: Spectral은 단일 사양을 검사합니다. 이전 버전과 새 버전을 비교하지 않으므로 주요 변경 사항 검출에는 oasdiff 같은 diff 도구를 함께 사용해야 합니다.

vacuum: Spectral 규칙을 빠르게 실행하기

Spectral이 규칙 작성의 기준이라면, vacuum은 실행 속도에 초점을 둔 MIT 라이선스의 Go 기반 린터입니다. Spectral 규칙 세트와 호환되므로, 기존 규칙을 유지하면서 대규모 사양에서 더 빠른 피드백을 얻을 수 있습니다.

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml
Enter fullscreen mode Exit fullscreen mode

-d 옵션은 규칙별 상세 결과를 보여줍니다. 사전 커밋 훅이나 빠른 CI 루프에서 특히 유용합니다.

기존 Spectral 규칙 파일도 적용할 수 있습니다.

vacuum lint -d -r .spectral.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

vacuum은 린트 외에도 같은 사양에서 HTML 보고서와 문서를 생성할 수 있습니다. Node 런타임 없이 단일 바이너리로 실행되므로 컨테이너 환경에도 쉽게 넣을 수 있습니다.

가장 적합한 용도: 기존 Spectral 규칙 세트로 대규모 OpenAPI 사양을 빠르게 검사할 때

한계: 규칙 세트 생태계와 문서는 Spectral 중심입니다. 일반적으로는 Spectral 방식으로 규칙을 작성하고 vacuum에서 실행하게 됩니다.

Redocly CLI: 다중 파일 OpenAPI를 번들링하기

Redocly CLI는 MIT 라이선스 도구입니다. 린트도 지원하지만, 핵심 기능은 여러 $ref 파일로 나뉜 OpenAPI 사양을 하나의 파일로 합치는 bundle 명령입니다.

npm install -g @redocly/cli

redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

대규모 API는 리소스별로 사양 파일을 분리하는 편이 관리하기 쉽습니다.

openapi/
├── openapi.yaml
├── paths/
│   ├── users.yaml
│   └── orders.yaml
└── schemas/
    ├── User.yaml
    └── Order.yaml
Enter fullscreen mode Exit fullscreen mode

하지만 많은 도구, 목 서버, 문서 시스템은 단일 OpenAPI 파일을 기대합니다. 이때 CI에서 번들 아티팩트를 생성하면 됩니다.

mkdir -p dist
redocly bundle openapi/openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

이 방식은 변경 사항을 읽기 쉽게 만들고 병합 충돌을 줄입니다. 이는 Git-native API 디자인 워크플로우에서 특히 중요합니다.

가장 적합한 용도: $ref 기반의 다중 파일 OpenAPI 프로젝트를 검사하고 단일 배포용 아티팩트로 만들 때

한계: 기본 린트 규칙은 전체 Spectral 규칙 세트보다 가볍습니다. 많은 팀이 번들링에는 Redocly를, 세부 스타일 검증에는 Spectral 또는 vacuum을 함께 사용합니다.

openapi-generator: 사양에서 SDK, 서버 스텁, 문서 생성하기

openapi-generator는 Apache-2.0 라이선스 도구로, OpenAPI 사양에서 클라이언트 SDK, 서버 스텁, 문서를 생성합니다.

npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

-g 옵션으로 생성 대상을 선택합니다.

# Go 클라이언트
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go

# Python 클라이언트
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python

# Java 클라이언트
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
Enter fullscreen mode Exit fullscreen mode

사양 변경 시 CI에서 생성 명령을 실행하면 SDK가 API 계약에서 벗어나는 일을 줄일 수 있습니다. 이 방식은 API 디자인 원칙에서 다루는 스키마 우선 및 계약 중심 접근 방식과 맞닿아 있습니다.

가장 적합한 용도: API 사양과 클라이언트 SDK, 서버 스텁, 문서를 동기화할 때

한계: JDK 11 이상이 필요합니다. 생성 코드는 즉시 배포할 완성품이 아니라 시작점인 경우가 많으며, 생성기 품질은 언어와 대상별로 다를 수 있습니다. 배포 전 생성 결과를 검토하세요.

oasdiff: PR에서 주요 변경 사항 차단하기

린터는 사양 형식과 스타일 문제를 찾아줍니다. 하지만 응답 필드를 제거하거나 필드 타입을 바꿨을 때 기존 클라이언트가 깨지는지는 알려주지 못합니다.

oasdiff는 Apache-2.0 라이선스의 Go 도구로, OpenAPI 사양의 두 버전을 비교해 특히 주요 변경 사항을 찾아냅니다.

go install github.com/oasdiff/oasdiff@latest

oasdiff breaking old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

주요 명령은 다음과 같습니다.

# 기존 소비자를 깨는 변경 사항만 확인
oasdiff breaking old-openapi.yaml new-openapi.yaml

# 사람이 읽기 쉬운 전체 변경 로그 생성
oasdiff changelog old-openapi.yaml new-openapi.yaml

# 전체 기계 판독용 차이 확인
oasdiff diff old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

PR 검사에서는 기준 브랜치의 사양과 현재 브랜치의 사양을 비교하도록 구성할 수 있습니다.

oasdiff breaking \
  main/openapi.yaml \
  dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

이렇게 하면 주요 변경 사항을 새벽 운영 장애가 아니라 빌드 실패로 처리할 수 있습니다.

가장 적합한 용도: CI와 PR 검사에서 주요 변경 사항을 게이팅(gating)할 때

한계: 사양끼리 비교하므로 실제 API와 OpenAPI 문서를 최신 상태로 유지해야 합니다. 스타일 린트 기능은 없으므로 Spectral 또는 vacuum과 조합하세요.

Optic: 린트와 diff를 함께 수행하는 레거시 옵션

Optic은 MIT 라이선스 도구입니다. OpenAPI 린트와 diff를 하나의 도구에서 수행하며, 두 버전을 비교해 주요 변경 사항을 표시하고 스타일 규칙도 적용합니다. 관찰된 테스트 트래픽에서 사양을 생성하는 기능도 제공합니다.

npm install -g @useoptic/optic

optic diff old-openapi.yaml new-openapi.yaml --check
Enter fullscreen mode Exit fullscreen mode

다만 운영 도구를 선택할 때는 유지보수 상태를 확인해야 합니다. Optic의 공개 저장소는 2026년 초에 아카이브되었고, 더 이상 적극적으로 유지보수되지 않습니다. MIT 소스는 계속 실행할 수 있지만 새로운 규칙이나 보안 패치를 기대하기는 어렵습니다.

새 프로젝트에서 주요 변경 사항을 감지해야 한다면 유지보수 중인 oasdiff를 우선 고려하세요. Optic은 기존 파이프라인에서 이미 사용 중인 경우에 주로 발견될 수 있습니다.

가장 적합한 용도: 이미 Optic에 투자했거나 단일 CLI에서 린트와 diff를 모두 실행하는 기존 환경

한계: 2026년 초부터 유지보수되지 않습니다. 레거시 도구로 취급하고 마이그레이션 경로를 준비하세요.

Apidog가 적합한 곳과 적합하지 않은 곳

Apidog는 오픈 소스가 아니며 OpenAPI 스타일 규칙을 린트하거나 강제하지 않습니다. 스타일 린트는 Spectral, vacuum, Redocly CLI가 담당합니다.

Apidog은 다른 문제를 해결합니다. 여러 개의 개별 바이너리를 조합하는 대신, 엔드포인트와 데이터 스키마를 설계하고 결과를 OpenAPI로 내보낼 수 있는 통합 작업 공간을 제공합니다. 내보낸 OpenAPI 파일은 앞서 소개한 오픈 소스 도구 체인에서 그대로 사용할 수 있습니다.

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml
Enter fullscreen mode Exit fullscreen mode

apidog-cli는 다음 명령 그룹을 제공합니다.

  • endpoint
  • schema
  • mock
  • import
  • export

예를 들어 Apidog에서 설계한 결과를 내보낸 뒤, 번들링과 주요 변경 사항 검사를 이어서 실행할 수 있습니다.

apidog export --format openapi -o openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml
oasdiff breaking previous-openapi.yaml dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

전체 명령어는 Apidog CLI 완전 가이드에서 확인할 수 있습니다.

Apidog는 오픈 소스 린터를 대체하지 않습니다. OpenAPI를 설계하고 내보내는 상업적 통합 옵션이며, 린트와 변경 감지는 오픈 소스 CLI 도구로 계속 처리할 수 있습니다.

선택 방법

대부분의 팀은 도구 하나만 사용하지 않습니다. 작업별로 두세 개 이상의 도구를 조합하는 편이 일반적입니다.

도구 가장 적합한 용도 설치 오픈 소스? 비고
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 통합 디자인 + OpenAPI 내보내기 npm i -g apidog-cli 아니요 (무료 티어) 린터가 아닌 내보내기 옵션

실용적인 기본 조합은 다음과 같습니다.

# 1. 스타일 및 구조 검사
spectral lint openapi.yaml --ruleset .spectral.yaml

# 2. 다중 파일 사양 번들링
redocly bundle openapi.yaml -o dist/openapi.yaml

# 3. 이전 버전 대비 주요 변경 사항 검사
oasdiff breaking previous-openapi.yaml dist/openapi.yaml

# 4. 클라이언트 SDK 생성
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

도구를 더 넓은 API 디자인 및 테스트 환경에서 검토하려면 API 디자인 및 테스트를 위한 Swagger 대안과 REST API 디자인 방법도 참고하세요.

마무리

API 디자인을 위한 오픈 소스 CLI 도구 체인은 충분히 성숙했으며 무료로 운영할 수 있습니다.

  • Spectral, vacuum: 스타일 및 구조 린트
  • Redocly CLI: 다중 파일 사양 번들링
  • openapi-generator: SDK, 서버 스텁, 문서 생성
  • oasdiff: 주요 변경 사항 차단
  • Optic: 기존 환경에서만 고려할 레거시 옵션

이 도구들을 CI에 연결하면 푸시와 PR마다 API 계약을 자동으로 검증할 수 있습니다. 사용자별 비용이나 벤더 종속 없이 실행할 수 있다는 점도 장점입니다.

하나의 통합 도구에서 엔드포인트와 스키마를 설계한 뒤 OpenAPI를 내보내고 싶다면 Apidog를 다운로드하여 apidog-cli를 사용할 수 있습니다. 이는 오픈 소스 린터를 대체하는 도구가 아니라, 해당 도구 체인과 함께 사용할 수 있는 상업적 동반 옵션입니다.

어떤 조합을 선택하든 목표는 같습니다. 사용자가 문제를 발견하기 전에, 터미널과 CI에서 API 디자인 문제를 발견하는 것입니다.

Top comments (0)