Rihpig

Posted on Jul 14 • Originally published at apidog.com

최고의 경량 CLI API 설계 도구

대부분의 API 디자인 도구는 필요한 작업보다 무겁습니다. 명명 규칙을 확인하고, 분할된 사양을 하나로 묶고, 호환성을 깨는 필드 변경을 감지하려고 할 때마다 데스크톱 앱을 실행하거나 서비스를 연결할 필요는 없습니다. 터미널에서는 대부분의 작업을 설정 거의 없이 명령어 하나로 처리할 수 있습니다.

지금 Apidog 사용해 보기

이 글에서는 API 디자인 툴체인을 가볍게 구성하는 방법을 다룹니다. 소개하는 도구는 빠르게 설치하고, 바로 실행하며, 각각 하나의 작업에 집중합니다. 핵심 기능을 사용하기 위해 계정을 만들거나 긴 설정 파일을 작성할 필요가 없으며, 대부분 단일 바이너리 또는 npx 호출만으로 CI에 추가할 수 있습니다.

전체 설계 흐름이 필요하다면 먼저 API 디자인 방법을 확인하세요. 이 글에서는 그 흐름에서 사용할 CLI 도구를 선택하고 자동화하는 데 집중합니다.

다룰 도구는 다음과 같습니다.

사양 린터
유효성 검사와 번들링을 수행하는 도구
SDK, 서버 스텁, 문서 생성기
호환성 파괴 변경을 감지하는 두 가지 도구
터미널에서 엔드포인트와 스키마를 설계하는 Apidog CLI

이 도구들은 모두 OpenAPI Specification을 공통 형식으로 사용합니다. 즉, 한 도구의 출력물을 다음 도구의 입력으로 바로 전달할 수 있습니다.

API 디자인에서 CLI 도구가 가벼운 기준

여기서 말하는 경량은 기능 수가 아니라 설치와 실행 과정의 마찰이 적다는 뜻입니다. 다음 세 가지를 기준으로 도구를 선택하세요.

작은 설치 크기와 빠른 시작

전역 설치 없이 실행 가능한 단일 바이너리 또는 npx 명령이 유리합니다. 새 컨테이너에서도 몇 분의 초기 설정 없이 실행할 수 있어야 합니다.
첫 결과까지 필요한 설정이 적음

설정 파일을 만들기 전에도 OpenAPI 파일 하나를 지정하면 유효성 검사, 린트 또는 번들링 결과를 확인할 수 있어야 합니다.
터미널 우선, 스크립트 가능

명확한 종료 코드와 구조화되거나 grep 가능한 출력이 필요합니다. 그래야 로컬 환경에서 실행한 동일한 명령을 PR 검사와 CI에서 그대로 사용할 수 있습니다.

아래 도구는 대체로 설치 부담이 작은 순서로 정리했습니다.

Redocly CLI: 설치 없이 린트하고 번들링하기

Redocly CLI는 npx로 바로 실행할 수 있습니다. 일회성 검사, CI, 동료의 개발 환경에서 빠르게 확인할 때 적합합니다. MIT 라이선스이며, 핵심 작업은 린트와 번들링입니다.

npx @redocly/cli@latest lint openapi.yaml
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

여러 파일로 나뉜 사양을 관리한다면 bundle을 먼저 실행하세요.

openapi/
├── openapi.yaml
├── paths/
│   ├── users.yaml
│   └── orders.yaml
└── components/
    └── schemas.yaml

이런 구조에서 번들 결과를 생성하면 모의 서버, 문서 사이트, SDK 생성기 등 단일 파일을 기대하는 도구에 전달할 수 있습니다.

npx @redocly/cli@latest bundle openapi/openapi.yaml \
  -o dist/openapi.yaml

사양을 리소스별 파일로 분리하면 diff가 읽기 쉬워지고 병합 충돌도 줄어듭니다. 이는 Git 기반 API 디자인 워크플로우에서 특히 유용합니다. Redocly는 1MB 사양도 1초 이내에 린트할 수 있습니다.

적합한 용도

여러 파일로 구성된 OpenAPI 사양 번들링
설치 없이 빠르게 수행하는 기본 유효성 검사와 린트

한계

기본 규칙은 빠른 검사에는 좋지만, 팀 전체의 상세한 스타일 가이드를 강제하기에는 부족할 수 있습니다. 스타일 규칙은 Spectral로 보완하는 구성이 일반적입니다.

Spectral: API 스타일 가이드를 코드로 적용하기

Stoplight Spectral은 API 설명 문서를 위한 오픈소스 린터입니다. Apache-2.0 라이선스가 적용되며 OpenAPI 3.x, OpenAPI 2.0, AsyncAPI, Arazzo 문서를 검사할 수 있습니다.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

처음에는 설정 파일 없이 실행해도 됩니다. Spectral은 내장된 oas 규칙 세트를 적용해 누락된 설명, 잘못된 예제, 구조 문제를 표시합니다.

팀 규칙을 적용하려면 리포지토리에 규칙 파일을 추가하세요.

# .spectral.yaml
extends:
  - spectral:oas

rules:
  operation-operationId:
    description: 모든 작업에는 operationId가 필요합니다.
    given: $.paths[*][get,put,post,delete,options,head,patch,trace]
    then:
      field: operationId
      function: truthy

그다음 PR 검사에서 동일한 규칙을 실행합니다.

spectral lint openapi.yaml --ruleset .spectral.yaml

이 방식으로 다음과 같은 팀 규칙을 자동화할 수 있습니다.

모든 operation에 operationId 요구
공통 오류 스키마 사용
URL 경로 명명 규칙 적용
필수 설명 및 예제 검사

이런 규칙은 리포지토리에 함께 저장되므로 모든 기여자에게 동일하게 적용됩니다. API 디자인 원칙의 스타일 가이드를 실행 가능한 검사 규칙으로 바꾸는 방법입니다.

적합한 용도

팀 API 스타일 가이드 강제
사양 품질 기준을 CI에서 자동 검사

한계

Spectral은 단일 사양을 검사합니다. 이전 버전과 새 버전을 비교해 호환성 파괴 변경을 찾으려면 oasdiff 같은 diff 도구를 함께 사용해야 합니다.

oasdiff: 단일 바이너리로 호환성 파괴 변경 차단하기

린터는 사양의 구조와 스타일 문제를 알려줍니다. 하지만 userName을 name으로 바꿨을 때 기존 클라이언트가 깨지는지는 알려주지 못합니다.

oasdiff는 두 OpenAPI 사양을 비교해 그 차이를 분석합니다. Apache-2.0 라이선스의 단일 Go 바이너리이며, 별도 런타임이 필요하지 않습니다.

go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml

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

# 기존 소비자를 깨는 변경만 출력
oasdiff breaking old-openapi.yaml new-openapi.yaml

# 사람이 읽기 쉬운 전체 변경 목록
oasdiff changelog old-openapi.yaml new-openapi.yaml

# 기계가 처리할 수 있는 전체 차이 출력
oasdiff diff old-openapi.yaml new-openapi.yaml

PR에서 기준 브랜치의 사양과 변경된 사양을 비교하도록 연결하면 됩니다.

oasdiff breaking \
  main/openapi.yaml \
  openapi.yaml

이 명령이 실패하면 호환성 파괴 변경을 배포 전에 차단할 수 있습니다. 새벽 3시의 장애 알림을 빌드 실패로 바꾸는 방식입니다.

적합한 용도

CI에서 호환성 파괴 변경 차단
설정 부담이 적은 OpenAPI 버전 비교

한계

oasdiff는 사양끼리 비교합니다. 실제 API 구현과 OpenAPI 사양이 동기화되어 있어야 결과가 유효합니다. 스타일 린트 기능은 없으므로 Spectral 또는 Redocly와 조합하세요.

Optic: 린트와 diff를 하나의 CLI로 사용하기

Optic은 OpenAPI 린트와 버전 간 diff를 하나의 CLI에서 제공하는 MIT 라이선스 도구입니다.

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check

다만 신규 도입 전에 유지 관리 상태를 확인해야 합니다. Optic의 공개 저장소는 2026년 1월에 보관되었고 프로젝트는 더 이상 유지 관리되지 않습니다. MIT 소스 코드는 계속 실행할 수 있지만, 새 규칙이나 보안 패치는 제공되지 않습니다.

새 프로젝트에서 호환성 파괴 변경 감지가 필요하다면 유지 관리 중인 oasdiff가 더 가볍고 적합한 선택입니다. Optic은 기존 파이프라인에서 여전히 사용될 수 있으므로, 레거시 도구로 인식하고 마이그레이션 계획을 세우는 것이 좋습니다.

적합한 용도

이미 Optic을 사용 중이며 린트와 diff를 하나의 CLI로 유지해야 하는 팀

한계

2026년 초부터 유지 관리되지 않음
신규 프로젝트의 기본 선택지로는 권장하기 어려움

openapi-generator: OpenAPI를 SDK, 스텁, 문서로 생성하기

디자인은 다른 개발자가 실제로 사용할 수 있을 때 완성됩니다. openapi-generator는 OpenAPI 사양에서 여러 언어의 클라이언트 SDK, 서버 스텁, 문서를 생성합니다. Apache-2.0 라이선스이며 JVM에서 실행됩니다.

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client

생성기만 바꾸면 다른 언어로도 출력할 수 있습니다.

# 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

사양이 변경될 때마다 CI에서 생성기를 실행하면 SDK가 계약과 분리되는 문제를 줄일 수 있습니다. 사양을 진리의 원천으로 두고 나머지 산출물을 생성하는 방식은 디자인 우선 API 개발의 핵심입니다.

적합한 용도

클라이언트 SDK, 서버 스텁, 문서를 사양과 동기화
여러 언어의 API 소비자에게 일관된 시작점 제공

한계

JDK 11 이상이 필요함
단일 바이너리 도구보다 무거움
생성 코드는 출발점이며, 생성기 품질은 언어별로 다를 수 있음

Apidog CLI: 터미널에서 엔드포인트와 스키마 설계하기

앞의 도구는 이미 존재하는 OpenAPI 사양을 검사하거나 변환합니다. Apidog는 그 이전 단계, 즉 엔드포인트와 데이터 스키마를 설계하는 작업을 다룹니다.

CLI는 전체 데스크톱 앱이 아니라 apidog-cli 바이너리로 제공되며 npm에서 설치할 수 있습니다.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>

apidog endpoint list
apidog schema list

apidog export --format openapi -o openapi.yaml

Apidog CLI는 다음 명령어 그룹을 제공합니다.

endpoint: 엔드포인트 관리
schema: 데이터 모델 관리
security-scheme: 인증 방식 관리
folder: API 구조 관리
mock: 모의 데이터와 API 관련 작업
import / export: OpenAPI 등 사양 가져오기와 내보내기

출력은 agentHints.nextSteps를 포함한 구조화된 JSON으로 제공되므로 스크립트의 다음 단계와 연결할 수 있습니다. 전체 명령어는 Apidog CLI 전체 가이드를 참고하세요.

예를 들어, Apidog에서 설계한 API를 OpenAPI로 내보낸 뒤 기존 CLI 파이프라인으로 전달할 수 있습니다.

# 1. 설계 결과를 OpenAPI로 내보내기
apidog export --format openapi -o openapi.yaml

# 2. 스타일과 구조 검사
spectral lint openapi.yaml

# 3. 여러 파일 사양을 단일 파일로 번들링
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

# 4. 이전 계약과 비교
oasdiff breaking old-openapi.yaml dist/openapi.yaml

중요한 점은 Apidog가 OpenAPI 린터나 스타일 규칙 엔진은 아니라는 것입니다. 린트와 스타일 강제는 Spectral 또는 Redocly의 역할입니다. Apidog은 오픈소스가 아닌 상용 제품이며 무료 계층을 제공합니다. 역할은 엔드포인트와 스키마를 설계하고, 깨끗한 OpenAPI를 내보내 이후 도구 체인에 전달하는 것입니다.

적합한 용도

하나의 공간에서 엔드포인트와 데이터 스키마 설계
OpenAPI를 내보내 CI 린트, diff, SDK 생성 단계에 연결

한계

린터가 아님
오픈소스가 아님
Spectral, Redocly, oasdiff를 대체하지 않고 보완함

선택 방법

대부분의 팀은 하나만 선택하지 않습니다. API 수명 주기의 작업별로 도구를 조합하세요.

도구	가장 적합한 용도	설치	오픈 소스?	비고
Redocly CLI	번들링 + 빠른 린트	`npx @redocly/cli@latest`	예 (MIT)	설치 없이 실행 가능, 다중 파일 사양에 적합
Spectral	스타일 가이드 린팅	`npm i -g @stoplight/spectral-cli`	예 (Apache-2.0)	제로 설정 시작, 사용자 지정 규칙 지원
oasdiff	호환성 파괴 변경 감지	`go install github.com/oasdiff/oasdiff@latest`	예 (Apache-2.0)	단일 Go 바이너리, 유지 관리됨
Optic	하나의 도구에서 린트 + diff	`npm i -g @useoptic/optic`	예 (MIT)	2026년 1월 저장소 보관, 레거시
openapi-generator	SDK / 스텁 / 문서 생성	`npm i -g @openapitools/openapi-generator-cli`	예 (Apache-2.0)	JDK 11+ 필요, 이 목록에서 가장 무거움
Apidog CLI	엔드포인트 설계 + 사양 내보내기	`npm i -g apidog-cli`	아니오 (무료 계층)	린터가 아니며 OpenAPI 설계와 내보내기에 집중