Redocly CLI는 훌륭한 도구입니다. OpenAPI 파일을 린트(lint)하거나, 다중 파일 스펙을 하나로 묶거나, 터미널에서 Redoc 문서를 빌드하는 데 사용해 본 적이 있다면 이미 알고 계실 겁니다. 그렇다면 굳이 Redocly CLI 대안을 찾아야 할 이유가 무엇일까요?
일반적으로 이는 형태의 문제로 귀결됩니다. Redocly CLI는 린트, 번들, 분할, 병합, 문서 빌드와 같은 코드 우선 전문가 도구에 집중합니다. 이는 일부 팀에게는 완벽하지만, 다른 팀에게는 부족할 수 있습니다. API를 설계하고, 모의(mock)하고, 테스트하는 기능까지 한 도구에서 원한다면, CLI는 그런 도구가 되려고 하지 않으며, 그래서도 안 됩니다.
이 글은 호스팅된 Redocly 문서 제품이 아닌 Redocly CLI(오픈 소스 @redocly/cli 패키지)에 관한 것입니다. 호스팅된 문서 플랫폼 또는 Redoc 자체를 비교하고 있다면, 대신 API 문서화를 위한 Redocly 대안에 대한 총정리를 읽어보세요. 이 게시물은 redocly lint 및 redocly bundle을 입력하고 자신의 워크플로에 맞는 다른 도구가 무엇인지 알고 싶은 사람들을 위한 것입니다.
Redocly CLI가 실제로 잘하는 것
Redocly CLI는 오픈 소스이며 터미널 기반입니다. 한 번 설치하면 작업을 깔끔하게 수행하는 엄선된 명령어 세트를 얻을 수 있습니다. Redocly CLI 문서에 모든 내용이 나와 있지만, 여기서는 요약 버전을 소개합니다.
린팅(Linting)이 Redocly CLI의 핵심 강점입니다. redocly lint는 OpenAPI, AsyncAPI, Arazzo 또는 Open-RPC 설명을 검증한 다음 그 위에 스타일 가이드 규칙을 실행합니다. 모든 것은 redocly.yaml 파일을 통해 구성합니다: 내장된 규칙 세트(minimal, recommended, recommended-strict 또는 spec)를 선택하거나 자신만의 사용자 지정 규칙을 작성할 수 있습니다. 여러 팀에 걸쳐 CI에서 일관된 API 디자인을 적용하려면 이러한 구성 기반 거버넌스는 능가하기 어렵습니다.
npm install -g @redocly/cli@latest
redocly lint openapi.yaml
번들(Bundle), 분할(Split), 병합(Join)은 스펙의 내부 처리를 담당합니다. redocly bundle은 $ref 포인터를 따라 하나의 통합된 파일을 생성합니다. redocly split은 그 반대로, 단일 설명을 다중 파일 레이아웃으로 분할합니다. redocly join (실험적 기능)은 여러 OpenAPI 파일을 하나로 병합합니다.
redocly bundle openapi.yaml --output dist/openapi.json
문서는 build-docs에서 생성됩니다. 이는 독립형 Redoc HTML 페이지를 생성하며, preview-docs는 라이브 로컬 미리보기를 제공합니다.
redocly build-docs openapi.yaml -o docs.html
따라서 "스타일 가이드에 따라 검증하고, 스펙을 번들링하고, Redoc 문서를 모두 터미널에서 제공하는 것"이 필요한 경우 Redocly CLI는 강력한 기본 선택입니다. 많은 팀이 Redocly CLI를 유지해야 합니다. 다른 도구를 찾아야 하는 이유는 품질이 아니라 범위에 있습니다.
사람들이 대안을 찾는 이유
몇 가지 공통적인 패턴이 반복해서 나타납니다:
- 린팅과 문서화뿐 아니라 올인원 플랫폼을 원합니다. Redocly CLI는 API 테스트를 실행하지 않으며 모의 서버를 호스팅하지 않습니다. 설계, 모의(mocking) 및 테스트 러너도 필요하다면, 주변에 도구 체인을 구축해야 합니다.
- CLI와 함께 GUI를 원합니다. Redocly는 본질적으로 코드 우선 도구입니다. 팀에 시각적인 작업을 선호하는 사람이 있다면, 터미널 전용 거버넌스는 설득하기 어렵습니다.
- CI를 위한 내장 테스트 러너를 원합니다. 린팅은 스펙 문제를 찾아냅니다. 하지만 실행 중인 API가 제대로 작동하는지는 알려주지 않습니다. 이는 별도의 도구입니다.
- 다섯 가지 도구를 한데 엮고 싶지 않습니다. 린트에는 Spectral, 번들 및 문서에는 Redocly, 테스트에는 Postman 또는 Newman, 모의(mock)에는 다른 도구를 사용하는 식입니다. 이는 작동하지만, 유지 관리해야 할 부분이 너무 많습니다.
각 요점은 다른 대안을 가리킵니다. 이제 매치업해 봅시다.
실제로 원했던 것을 기준으로 한 최종 후보 목록
전체 API 수명 주기를 위한 단일 플랫폼을 원한다면 Apidog
Apidog는 설계, 모의(mocking), 테스트, 문서화를 한곳에서 제공하는 올인원 API 플랫폼이며, 가져오기(import), 내보내기(export), CI 테스트 실행을 위한 CLI를 제공합니다. 린터, 번들러, 테스트 러너, 모의 서버를 한데 묶는 대신 전체 수명 주기를 위한 단일 도구를 선호할 때 적합한 선택입니다.
이제 솔직한 부분을 이야기하겠습니다. Apidog에는 Redocly의 lint와 같은 구성 가능하고 코드 우선적인 사용자 지정 규칙 세트가 있는 스타일 가이드 린터가 없습니다. apidog lint 명령어는 없으며, CLI를 통해 Spectral 또는 Redocly 스타일의 사용자 지정 규칙을 작성할 방법도 없습니다. Apidog는 스펙을 가져올 때 구조를 검증하지만, 엄격하고 사용자 지정 가능한 디자인 거버넌스가 유일하게 중요한 사항이라면 Apidog만으로는 redocly lint를 대체할 수 없습니다. 이 작업에는 Spectral과 함께 사용하세요. 이 부분은 나중에 다시 다루겠습니다.
Apidog가 Redocly CLI가 제공하지 않는 것들: 시각적 디자이너, 내장 모의 서버, 시각적 테스트 빌더, 그리고 CI 테스트 러너입니다. CLI는 터미널에서 처리해야 하는 부분을 담당합니다.
# 설치 및 인증 (앱에서 토큰 가져오기: 아바타 > 계정 설정 > API 접근 토큰)
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
# 프로젝트에 스펙 가져오기 (다중 파일 $refs 검증 + 해결)
apidog import --project 123456 --format openapi --file ./openapi.json
# 단일 통합 파일 내보내기 및 OpenAPI 버전 선택
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# 여러 보고서 형식으로 CI에서 테스트 시나리오 실행
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
apidog import는 수집 시 검증 작업을 수행하며, apidog export는 내보낼 때 번들링 작업을 수행합니다(단일 파일을 출력하고 OAS 버전을 업그레이드할 수 있습니다). 전체 명령어 목록은 Apidog CLI 문서에 있으며, Apidog CLI 전체 가이드에서는 각 플래그에 대해 자세히 설명합니다. 가장 적합한 대상: 설계, 모의(mock), 테스트, 문서를 한곳에서 원하는 팀.
Redocly에서 린터만 원했다면 Spectral
redocly lint만 사용한다면 플랫폼을 바꿀 필요가 없습니다. Stoplight의 Spectral은 Redocly의 린팅과 가장 직접적으로 겹치는 오픈 소스 규칙 기반 린터입니다. YAML로 규칙을 작성하고, 모든 OpenAPI 또는 AsyncAPI 문서에 대해 실행하며, CI에 연결할 수 있습니다.
Spectral과 Redocly의 린터는 서로 가까운 사촌 관계입니다. 둘 다 구성 기반이며, 규칙 세트를 제공하고, 사용자 지정 규칙을 작성할 수 있습니다. 둘 중 하나를 선택하는 것은 종종 생태계 적합성과 팀이 이미 알고 있는 규칙 세트 형식에 따라 달라집니다. Spectral OpenAPI 린팅 심층 분석은 규칙 작성법을 다루며, 더 넓은 API 린팅 가이드는 전체 그림을 원할 경우 린팅 환경을 비교합니다. 가장 적합한 대상: 순수하고 사용자 지정 가능한 스펙 린팅이 진정으로 필요한 팀.
주로 문서를 원했다면 Scalar 또는 Bump.sh
Redocly CLI에서 build-docs 부분이 중요했다면, 대안은 플랫폼이 아닌 문서화 도구입니다. Scalar와 Bump.sh는 모두 OpenAPI 설명을 호스팅되고 탐색 가능한 참조 문서로 변환하며, 각각 고유한 모양과 기능 세트를 가지고 있습니다. 이들은 린팅이나 테스트보다는 문서 경험에 중점을 둡니다. 가장 적합한 대상: 멋지고 유지보수하기 쉬운 API 참조 문서를 주요 목표로 하는 팀.
더 이상 실질적인 옵션이 아닌 swagger-cli
오래된 가이드에서 여전히 swagger-cli가 언급되는 것을 볼 수 있으므로 명확히 할 가치가 있습니다: swagger-cli는 더 이상 사용되지 않습니다. swagger-cli GitHub 저장소는 더 이상 유지 관리되지 않으며 Redocly CLI를 후속 도구로 가리킨다고 명시합니다.
이 도구는 항상 swagger-cli validate와 swagger-cli bundle 두 가지 명령어만 가지고 있었습니다. 스타일 규칙으로 린팅하거나 문서를 생성하거나 테스트를 실행하거나 모의(mock) 기능을 제공한 적이 없습니다. 현재 이 도구를 사용하고 있다면, 이 도구에서 벗어나야 합니다. swagger-cli 사용법에 대한 저희 가이드는 이 도구가 했던 일을 다루며, Redocly는 정확한 플래그 매핑과 함께 swagger-cli에서 마이그레이션하는 가이드까지 발행했습니다. 완전성을 위해 해당 매핑을 아래에 포함하겠습니다.
비교표
Redocly CLI가 처리하는 작업에 대한 옵션들을 비교했습니다. "사용자 지정 규칙 린트"는 사용자 지정 규칙 세트가 있는 구성 가능하고 코드 우선적인 스타일 가이드 린터를 의미합니다.
| 도구 | 사용자 지정 규칙 린트 | 번들 | 문서 | 모의(Mock) | 테스트 | GUI | 오픈 소스 | 가장 적합한 대상 |
|---|---|---|---|---|---|---|---|---|
| Redocly CLI | Yes | Yes | Yes (Redoc) | No | No | No | Yes | 터미널에서 코드 우선 린트, 번들 및 문서 거버넌스 |
| Apidog | No | Via export | Yes | Yes | Yes (CI runner) | Yes | No (freemium) | 설계, 모의, 테스트 및 문서를 위한 단일 플랫폼 |
| Spectral | Yes | No | No | No | No | No | Yes | 순수하고 사용자 지정 가능한 OpenAPI/AsyncAPI 린팅 |
| Scalar / Bump.sh | No | No | Yes | No | No | Yes | Varies | 호스팅된 API 참조 문서 |
| swagger-cli | No | Yes | No | No | No | No | Yes (deprecated) | 새로운 기능 없음, 유지 관리되지 않음 |
표에 대한 참고 사항: Apidog의 "Via export"는 apidog export가 하나의 통합된 파일을 내보낸다는 의미이며, 이는 redocly bundle을 실행하는 실제적인 이유를 충족하지만, 동일한 bundle 명령어는 아닙니다. 그리고 Apidog는 오픈 소스가 아닌 프리미엄(freemium)이며, Redocly CLI와 Spectral은 둘 다 오픈 소스입니다. 이러한 절충점들을 그대로 받아들이세요.
swagger-cli를 Redocly CLI 번들 플래그 매핑으로
더 이상 사용되지 않는 swagger-cli를 사용 중이고 번들링을 위해 Redocly를 사용하려는 경우, 플래그는 깔끔하게 매핑됩니다:
| swagger-cli | Redocly CLI | 의미 |
|---|---|---|
-o, --outfile <file> |
--output (or -o) |
표준 출력 대신 파일에 쓰기 |
-t, --type <json|yaml> |
--ext <json|yaml|yml> |
출력 파일 유형 |
-r, --dereference |
-d, --dereferenced |
모든 $refs를 완전히 인라인 처리 |
따라서 swagger-cli bundle -o output.json은 redocly bundle --output output.json이 됩니다.
명확한 권장 사항
단일 승자는 없습니다. 왜냐하면 올바른 답변은 Redocly CLI의 어떤 작업을 대체하려는지에 따라 달라지기 때문입니다.
거버넌스가 정확히 필요한 것이라면 Redocly CLI를 유지하세요. 터미널에서만 실행되는 가볍고 오픈 소스이며 구성 기반의 린터, 번들러, Redoc 문서 빌더는 정말 좋은 설정입니다. 여기에 있는 어떤 것도 적합한 도구를 포기할 이유는 되지 않습니다.
도구 체인을 조립하는 데 지쳐 터미널 부분에 CLI가 있는 단일 플랫폼에서 설계, 모의(mocking), 테스트 및 문서를 원한다면 Apidog를 선택하세요. 각 단계별로 별도의 도구를 유지 관리하는 것을 중단하고, GUI를 원하는 팀원들을 위해 GUI를 얻을 수 있습니다. 사용자 지정 규칙 린팅도 필요하다면 Spectral과 함께 사용해야 한다는 점을 명확히 이해하세요. CI/CD 가이드의 Apidog CLI는 테스트 러너가 파이프라인에 어떻게 통합되는지 보여주며, Apidog CLI 대 Newman은 많은 팀이 이미 사용하는 러너와 비교합니다. Apidog를 다운로드하여 신용카드 없이 무료로 사용해 볼 수 있습니다.
린팅이 전부라면 Spectral을 선택하세요. 단일 명령어를 대체하기 위해 플랫폼을 바꿀 필요는 없습니다.
솔직한 관점: Redocly는 코드 우선 CLI 전문가이며, Apidog는 올인원 시각적 플랫폼입니다. 이들은 서로 다른 패러다임이며, 단순히 대체할 수 있는 것이 아닙니다. 적합성에 따라 선택하세요.
자주 묻는 질문
Apidog가 Redocly CLI를 완벽하게 대체할 수 있나요? 아니요, 솔직히 말씀드리자면 그렇지 않습니다. Apidog는 더 많은 수명 주기(설계, 모의, 테스트, 문서)를 포괄하지만, redocly lint와 같은 사용자 지정 규칙 세트 린터는 없습니다. 엄격하고 구성 가능한 스펙 거버넌스가 주된 작업이라면 Redocly의 린터를 유지하거나 Spectral을 사용하세요. Apidog는 여러 도구 대신 전체 API 수명 주기를 위한 하나의 도구를 원할 때 유리합니다.
Apidog CLI에 lint 명령어가 있나요? 아니요. Apidog는 apidog import로 스펙을 가져올 때 구조를 검증하지만, apidog lint는 없으며 CLI를 통해 Spectral 또는 Redocly 스타일의 사용자 지정 규칙을 작성할 방법도 없습니다. 이를 위해서는 Apidog와 Spectral을 함께 사용하세요.
Redocly CLI 없이 OpenAPI 파일을 번들링할 수 있나요? 예. apidog export --project <id> --format openapi --output ./openapi.json은 단일 통합 파일을 내보내며 --oas-version으로 특정 OpenAPI 버전을 지정할 수 있습니다. 문자 그대로 bundle 명령어는 아니지만, 동일한 실제적인 필요를 충족합니다. 번들링만 원하고 다른 것은 원하지 않는다면, redocly bundle은 여전히 훌륭하고 집중된 선택입니다.
2026년에 swagger-cli를 사용해야 할까요? 아니요. swagger-cli는 더 이상 사용되지 않고 유지 관리되지 않으며, 자체 저장소에서도 Redocly CLI를 후속 도구로 가리킵니다. 이 도구는 항상 검증과 번들링만 수행했습니다. 해당 작업에는 Redocly CLI를 사용하거나, 나머지 수명 주기까지 원한다면 Apidog와 같은 플랫폼으로 전환하세요.
이 게시물과 Redocly 문서 플랫폼 비교의 차이점은 무엇인가요? 이 게시물은 오픈 소스 @redocly/cli 도구(린트, 번들, 분할, 병합, 문서 빌드)에 관한 것입니다. 호스팅된 Redocly 문서 제품 또는 문서 렌더러로서의 Redoc을 비교하고 있다면, 대신 API 문서화를 위한 Redocly 대안을 읽어보세요. 이 두 가지는 우연히 같은 이름을 공유하는 다른 제품들을 다룹니다. 스펙 자체에 대해서는 OpenAPI Specification이 진실의 원천이며, npm의 Redocly CLI에서 현재 설치 세부 정보를 찾을 수 있습니다.