만약 npm install -g @apidevtools/swagger-cli를 실행한 후 경고 메시지를 보고 여기에 오셨다면, 간단히 말씀드리자면 이 도구는 더 이상 유지보수되지 않습니다. GitHub의 swagger-cli 저장소에는 "거대한 사용자 기반의 기대를 따라가기 위한 유지보수 부담이 너무 커서 기여가 거의 없음"을 이유로 명백히 이 도구가 더 이상 사용되지 않는다고 명시되어 있습니다. README 자체에서도 Redocly CLI를 후속 도구로 안내하고 있습니다.
따라서 대체품이 필요합니다. 이 글은 특히 validate 및 bundle 기능을 수행하는 swagger-cli 터미널 도구에 대한 것입니다. 만약 Swagger Editor, SwaggerHub 또는 더 광범위한 디자인 스위트를 의미하는 것이라면, 대신 API 테스트도 가능한 7가지 Swagger 대체 도구를 읽어보세요.
swagger-cli가 어떤 작업을 했는지 살펴본 다음, 지금 사용해야 할 솔직한 대안 목록을 알아보겠습니다.
swagger-cli가 실제로 했던 일
어떤 대체품이 적절한지는 어떤 기능을 사용했는지에 따라 달라지므로, 정확하게 아는 것이 중요합니다.
swagger-cli에는 정확히 두 가지 명령어가 있었습니다:
# 스키마에 대해 Swagger 2.0 / OpenAPI 3.0 정의 유효성 검사 및 $ref 확인
swagger-cli validate openapi.yaml
# $ref 포인터를 따라 여러 파일 정의를 하나의 파일로 결합
swagger-cli bundle openapi.yaml -o bundled.json
bundle 명령어에는 몇 가지 옵션이 있었습니다: 파일에 쓰기 위한 -o/--outfile, JSON 또는 YAML을 선택하기 위한 -t/--type, 모든 $ref를 완전히 인라인화하기 위한 -r/--dereference, 그리고 들여쓰기를 위한 -f/--format입니다.
그것이 이 도구의 전부였습니다. 구조의 유효성을 검사하고 여러 파일로 된 스펙을 번들로 묶었습니다. 스타일 규칙으로 린팅하거나, 문서를 생성하거나, 테스트를 실행하거나, 어떤 것도 모의(mock)하지 않았습니다. 만약 swagger-cli가 스펙을 "린팅"한다고 주장하는 글을 보셨다면, 그것은 잘못된 정보입니다. 이 도구는 단지 OpenAPI 스키마에 대해 정의를 확인하고 참조를 해결했을 뿐입니다. 일부 대체 도구는 훨씬 더 많은 기능을 수행하므로 이 범위를 염두에 두십시오. 모든 기능이 필요하지 않을 수도 있습니다.
대안 목록
세 가지 도구가 swagger-cli를 사용하는 거의 모든 이유를 충족하며, 언급할 가치가 있는 몇몇 전문 도구도 있습니다. 솔직한 요약입니다.
Redocly CLI: 공식 후속 도구이자 가장 유사한 1:1 대체품
Redocly CLI (@redocly/cli, 바이너리 redocly)는 오픈 소스이며, swagger-cli 자체의 README에서 안내하는 도구입니다. Redocly는 심지어 swagger-cli에서 마이그레이션 가이드를 발행했습니다. 만약 터미널 유효성 검사기와 번들러를 그대로 대체하는 것이 목표라면, 여기서 시작하세요.
swagger-cli를 설치했던 것과 동일한 방식으로 설치합니다:
npm install -g @redocly/cli@latest
# 또는 설치 없이 실행
npx @redocly/cli@latest lint openapi.yaml
매핑은 깔끔합니다. swagger-cli의 validate는 redocly lint가 되어 스펙을 검사하고 구성 가능한 스타일 규칙을 적용합니다. swagger-cli의 bundle은 redocly bundle이 됩니다:
# swagger-cli bundle -o output.json
redocly bundle openapi.yaml --output output.json
다음은 번들 플래그 매핑을 나란히 비교한 것입니다:
| swagger-cli | Redocly CLI | 목적 |
|---|---|---|
-o, --outfile |
--output (또는 -o) |
파일에 쓰기 |
-t, --type |
--ext (json, yaml, yml) |
출력 형식 |
-r, --dereference |
-d, --dereferenced |
모든 $ref를 완전히 인라인화 |
한 가지 알아둘 점: redocly lint는 기본적으로 swagger-cli의 validate보다 더 많은 작업을 수행합니다. 스키마 확인뿐만 아니라 스타일 가이드 규칙 세트를 적용합니다. 만약 swagger-cli가 제공했던 단순한 구조적 유효성 검사만을 원한다면, spec 규칙만 포함된 redocly.yaml을 구성한 다음 redocly lint openapi.yaml을 실행하세요. 이러한 규칙 세트 동작은 Redocly의 약점이라기보다는 시그니처 강점입니다. 터미널 기반 거버넌스를 원하는 팀이 이를 선호하는 이유입니다. 규칙 세트를 조정(minimal, recommended, recommended-strict, spec)하거나 사용자 지정 규칙을 작성할 수 있습니다. 다른 린터와 함께 작동하는 방식에 대해서는 최고의 OpenAPI 린터 설정을 참조하십시오.
Redocly CLI는 swagger-cli의 두 가지 명령어를 넘어섭니다. 단일 설명을 다중 파일 구조로 split(번들의 역방향)하고, 여러 파일을 join(실험적)하며, 독립 실행형 Redoc HTML 문서를 빌드할 수 있습니다:
redocly build-docs openapi.yaml -o docs.html
이 도구가 하지 않는 것: API 테스트 실행 또는 모의(mock) 서버 호스팅. 이 도구는 코드 우선, 터미널 기반의 린트/번들/문서 도구이며, 탁월한 도구입니다. 필요한 것이 전부라면, 지금 읽기를 멈추고 마이그레이션할 수 있습니다.
Apidog: 유효성 검사 및 번들 이상의 기능을 원할 때
솔직하게 다시 생각해보세요. swagger-cli는 유효성을 검사하고 번들링하기 위해 실행하는 정적 스크립트였습니다. 하지만 대부분의 팀에게 유효성 검사 및 번들링은 목적을 위한 수단입니다. 스펙이 올바른지 확인하기 위해 유효성 검사를 하고, 휴대 가능하도록 번들링한 다음, 모의(mock)하고, 테스트하고, 문서화합니다. swagger-cli는 이러한 후속 단계를 다른 도구에 맡겼습니다.
Apidog는 그 간극을 메워줍니다. 이 도구는 올인원 API 플랫폼으로, 하나의 작업 공간에서 디자인, 모의(mock), 테스트, 문서를 처리하며, 가져오기(import), 내보내기(export), CI 테스트 실행을 담당하는 CLI를 포함합니다. swagger-cli가 파일을 제공했다면, Apidog는 그 파일로 구축된 살아있는 작업 공간을 제공합니다.
swagger-cli의 기억과 가장 직접적으로 연결되는 두 가지 명령어는 import와 export입니다. 먼저 CLI를 설치하고 인증하세요:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
토큰은 Apidog 앱 또는 웹에서 얻을 수 있습니다: 아바타, 계정 설정, API 접근 토큰 순서입니다. 이 토큰은 ~/.apidog/config.toml에 저장되므로, 절대로 출력하거나 커밋하지 마십시오.
가져오기(Import)는 유효성 검사 단계입니다. 이 명령어는 정의를 프로젝트로 가져오고 여러 파일로 된 $ref를 통합 리소스로 해결합니다. 파일이 잘못 구성된 경우, 가져오기 과정에서 이를 알려줍니다:
apidog import --project 123456 --format openapi --file ./openapi.json
가져오기는 OpenAPI 외에도 Postman, HAR, Insomnia, WSDL, JSON Schema 등 다양한 형식을 지원하여 소스가 혼합되어 있을 때 유용합니다.
내보내기(Export)는 추가 기능이 있는 번들 단계입니다. 이 명령어는 단일 통합 파일을 출력하며, 내보낼 때 OpenAPI 버전을 선택할 수 있습니다. 이는 하나의 명령어로 번들링과 선택적 스펙 업그레이드를 동시에 수행합니다:
# 한 번에 번들링하고 OpenAPI 3.1로 업그레이드
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# 또는 독립 실행형 HTML 문서 출력
apidog export --project 123456 --format html --output ./docs.html
CI의 경우, Apidog는 swagger-cli에는 없었던 단계를 추가합니다: 테스트 실행.
# 여러 보고서 형식으로 CI에서 테스트 시나리오 실행
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
# 또는 내보낸 컬렉션 파일에서 완전히 오프라인으로 실행
apidog run ./collection.apidog-cli.json
CLI는 또한 endpoint, schema, mock, environment, branch, test-suite, test-report를 포함한 프로젝트 리소스를 직접 관리합니다. 설정 세부 사항 및 모든 플래그에 대해서는 Apidog CLI 전체 가이드와 공식 Apidog CLI 문서를 참조하십시오.
이제 과장보다는 적합성이 중요하므로 솔직한 한계점을 말씀드리겠습니다. Apidog의 CLI는 가져오기 시 구조의 유효성을 검사하지만, Redocly의 lint처럼 구성 가능한 코드 우선 스타일 가이드 린터를 사용자 지정 규칙 세트와 함께 제공하지는 않습니다. apidog lint 명령어는 없으며, CLI를 통해 Spectral 스타일의 사용자 지정 규칙을 작성할 수도 없습니다. split 또는 join 기능도 없습니다. Apidog는 GUI 중심입니다. 디자인, 모의(mock), 시각적 테스트 구축 및 문서는 주로 데스크톱 또는 웹 앱에서 작성되며, CLI는 프로젝트에 대한 가져오기, 내보내기, CI 테스트 실행 및 리소스 관리를 처리합니다. 그리고 Apidog는 오픈 소스가 아닌 프리미엄 모델이므로, Redocly CLI 및 Spectral과는 다른 모델입니다.
Spectral: CI에서 순수하고 사용자 지정 가능한 린팅
만약 swagger-cli에서 정말 원했던 것이 파이프라인에서 엄격하고 주관적인 유효성 검사였다면, Stoplight의 전용 린터인 Spectral이 있습니다. 이 도구는 오픈 소스이며 한 가지 작업, 즉 OpenAPI (및 기타 JSON/YAML) 문서에 사용자 지정 가능한 규칙 세트를 적용하는 작업을 위해 만들어졌습니다.
Spectral은 모든 풀 리퀘스트에서 코드로서 자체 규칙으로 사내 스타일을 강제하고 싶을 때 빛을 발합니다. 이 도구는 번들링하거나, 문서를 생성하거나, 엔드포인트를 테스트하지 않습니다. 린팅만 합니다. 이를 번들러와 함께 사용하면 swagger-cli가 했던 작업의 집중된 버전과 실제 거버넌스를 다시 구축할 수 있습니다. Spectral OpenAPI 린팅 가이드는 규칙 세트 작성 방법을 설명하고, CI에서 OpenAPI 유효성 검사는 이를 파이프라인에 연결하는 방법을 다룹니다.
간략하게: openapi-generator 및 vacuum
두 가지 도구가 더 있으니, 정확하고 간략한 버전을 알려드립니다. openapi-generator는 코드 및 클라이언트 생성기입니다. 번들링하는 이유가 생성기에 공급하기 위함이었다면, 스펙을 직접 소비하므로 별도의 번들 단계가 전혀 필요 없을 수도 있습니다. vacuum은 Go로 작성된 빠르고 Spectral 호환 OpenAPI 린터로, 대규모 모노레포에서 린트 속도가 중요할 때 좋은 선택입니다. 두 도구 모두 그 자체로는 일반적인 유효성 검사 및 번들 대체품은 아니지만, 특정 요구 사항에 부합합니다.
비교표
swagger-cli 사용자들이 주로 신경 쓰는 기능들을 기준으로 옵션들을 비교했습니다.
| 도구 | 유효성 검사 | 번들 | 린트 규칙 | 문서 | 모의(Mock) | 테스트 | 오픈 소스 | 최적 용도 |
|---|---|---|---|---|---|---|---|---|
| swagger-cli | 예 | 예 | 아니요 | 아니요 | 아니요 | 아니요 | 예 (더 이상 사용 안 함) | 새로운 기능 없음; 유지보수되지 않음 |
| Redocly CLI | 예 (lint) |
예 | 예 (구성 가능) | 예 (Redoc HTML) | 아니요 | 아니요 | 예 | 거버넌스가 있는 터미널 유효성 검사/번들 대체품 |
| Apidog | 예 (가져오기 시) | 예 (내보내기 시, OAS 업그레이드 포함) | 구조적 유효성만, 사용자 지정 규칙 세트 없음 | 예 (앱 + 내보내기) | 예 | 예 (CLI 실행) | 아니요 (프리미엄) | 전체 API 라이프사이클을 위한 하나의 도구 |
| Spectral | 예 (린트 기반) | 아니요 | 예 (사용자 지정 규칙 세트) | 아니요 | 아니요 | 아니요 | 예 | CI에서 엄격하고 사용자 지정 가능한 린팅 |
| vacuum | 예 (린트 기반) | 아니요 | 예 (Spectral 호환) | 아니요 | 아니요 | 아니요 | 예 | 대규모 스펙에서 빠른 린팅 |
권장 사항
이것은 "모든 것이 훌륭하니 마음에 드는 것을 선택하세요"라는 상황이 아닙니다. 거의 모든 사람에게 적용되는 두 가지 명확한 경로가 있습니다.
즉각적인 대체품을 원한다면 Redocly CLI를 선택하세요. 이 도구는 공식 후속 도구이며 오픈 소스이고, 위에서 설명한 플래그 매핑을 통해 validate는 lint로, bundle은 bundle로 거의 기계적으로 마이그레이션할 수 있습니다. 만약 워크플로우가 진정으로 "터미널에서 유효성 검사 및 번들링"에 불과하고, 나중에 도구를 바꾸지 않고 거버넌스 규칙을 추가하고 싶다면, Redocly가 분명한 선택입니다. 이는 swagger-cli가 있었던 코드 우선 및 터미널 기반 환경을 유지시켜줍니다.
유효성 검사 및 번들링이 단지 시작에 불과했다면 Apidog를 선택하세요. 대부분의 팀은 스펙 자체만을 위해 유효성 검사를 하지 않습니다. 유효성 검사를 한 다음, 누군가는 개발을 위한 모의(mock)가 필요하고, 다른 누군가는 테스트를 작성하며, 또 누군가는 문서를 관리합니다. swagger-cli는 첫 번째 단계에서 멈췄고, 나머지는 Spectral, 번들러, Postman, Newman에서 조합해야 했습니다. Apidog는 가져오기(유효성 검사), 내보내기(번들 및 OAS 버전 업그레이드), 모의(mock), 테스트, 문서를 하나의 작업 공간으로 통합하며, CI에 속하는 부분에 대한 CLI를 제공합니다. 더 이상 정적이며 이제는 유지보수되지 않는 스크립트를 관리할 필요 없이, 전체 스펙을 번들링 후에도 유용하게 유지되는 곳으로 가져올 수 있습니다.
이것들은 동일한 것의 경쟁 버전이 아니라 다른 패러다임입니다. Redocly CLI는 터미널에서 순수하게 실행되는 경량의, 설정 기반 전문가 도구입니다. Apidog는 유능한 CLI를 우연히도 갖춘 올인원 플랫폼입니다. 하나의 도구에서 라이프사이클의 얼마나 많은 부분을 원하는지에 따라 선택하고 솔직해지세요. 만약 터미널에서 린트와 번들링만 원한다면, Redocly가 더 간결하고 무료입니다.
라이프사이클 접근 방식을 시도하고 싶다면, Apidog를 다운로드하고 기존 스펙을 가져오세요. 무료로 시작할 수 있으며, 신용카드 정보가 필요 없고, 몇 분 안에 번들링되고 버전 관리된 결과물을 확인할 수 있습니다.
자주 묻는 질문
swagger-cli는 여전히 유지보수되고 있나요?
아니요. swagger-cli GitHub 저장소는 더 이상 사용되지 않는 것으로 표시되어 있으며, 대규모 사용자 기반에 비해 기여가 적다는 이유로 더 이상 유지보수되지 않습니다. 여전히 설치 및 실행은 되지만, 수정이나 업데이트는 없을 예정이므로 마이그레이션을 계획하십시오.
swagger-cli를 대체하는 것은 무엇인가요?
프로젝트 자체의 README는 Redocly CLI를 후속 도구로 지목합니다. redocly lint는 swagger-cli validate를 대체하고 redocly bundle은 swagger-cli bundle을 대체합니다. Redocly는 심지어 전용 마이그레이션 가이드도 발행했습니다. 유효성 검사 및 번들링 이상을 원한다면, Apidog는 가져오기, 내보내기, 모의(mock), 테스트, 문서를 한 곳에서 처리합니다.
Apidog는 무료인가요?
Apidog는 프리미엄(freemium) 모델입니다. 신용카드 없이 시작할 수 있는 무료 티어가 있으며, 더 큰 팀과 고급 요구 사항을 위한 유료 플랜도 있습니다. 오픈 소스가 아니라는 점이 Redocly CLI 및 Spectral과의 주요 차이점인데, 오픈 라이선싱이 필수 요구 사항이라면 고려해야 합니다.
swagger-cli 워크플로우를 그대로 유지할 수 있나요?
가장 유사한 것은 Redocly CLI입니다. swagger-cli의 단순 구조적 validate를 모방하려면, spec 규칙만 포함된 redocly.yaml을 설정하고 redocly lint를 실행하십시오. 번들링의 경우, 명령어와 플래그가 거의 1대1로 매핑됩니다. 원래 도구의 범위에 대한 더 자세한 내용은 터미널에서 swagger-cli 사용하는 방법을 참조하십시오.