Apidog CLI 대 Redocly CLI: 어떤 API CLI를 사용해야 할까요?

이 두 도구는 모두 터미널에서 작동하고, OpenAPI를 지원하며, 팀이 API 사양에 대한 명령줄 워크플로우를 원할 때 나타납니다. 중복되는 부분은 여기까지입니다. 이들은 서로 다른 방향에서 인접한 문제를 해결하며, 잘못된 도구를 선택하면 테스트를 실행하지 않는 린터와 싸우거나, 단순히 빠른 구조적 검사만 원했음에도 불구하고 플랫폼에 의존하게 될 수 있습니다.

이것은 Apidog CLI와 Redocly CLI의 직설적인 명령줄 수준 비교입니다. 허수아비 같은 주장은 없습니다. Redocly CLI는 진정으로 훌륭한 오픈 소스 소프트웨어이며, 어떤 결론이 나오기 전에 이 도구가 정확히 어디에서 빛을 발하는지 보게 될 것입니다.

TL;DR 결론

이들은 중복되지만 서로 다른 문제를 해결합니다.

Redocly CLI(@redocly/cli, 바이너리 redocly)는 코드 우선 OpenAPI 전문가입니다: 사용자 정의 규칙 세트로 린트(lint)하고, 다중 파일 사양을 번들링하고, 분할 및 결합하며, 독립형 HTML 문서를 빌드합니다. 이것은 오픈 소스이며, 구성 중심적이고, 터미널 네이티브입니다. 사양이 진실의 원천이며 Git에 있다면, 이것은 명령줄에서 실행하는 거버넌스입니다.

Apidog CLI(apidog-cli, 바이너리 apidog)는 올인원 API 플랫폼의 명령줄 인터페이스입니다. 프로젝트에 대한 정의를 가져오고 내보내며, CI에서 JUnit 및 HTML 보고서와 함께 API 테스트 시나리오를 실행합니다. 동일한 사양이 별도의 도구로 이어 붙이는 대신 하나의 작업 공간에서 목업, 테스트 및 문서화되어야 할 때 그 가치를 발휘합니다.

가볍고 오픈 소스인 린터, 번들러, 문서 빌더를 순수하게 터미널에서 실행하고 싶다면 Redocly CLI를 선택하십시오. 전체 API 라이프사이클을 위한 하나의 도구를 선호한다면 Apidog를 선택하십시오. 이들은 또한 함께 작동할 수 있으며, 마지막 섹션에서 그 방법을 설명합니다.

두 가지 다른 철학

Redocly CLI는 파일 중심적이고 코드 우선입니다. 디스크에 있는 OpenAPI 문서가 여러분이 작업하는 대상입니다. 모든 명령, redocly lint, redocly bundle, redocly build-docs는 파일 경로를 취하고 계정이나 서버 개입 없이 로컬에서 작업을 수행합니다. 동작은 사양 옆의 저장소에 체크인하는 redocly.yaml 구성에 의해 형성됩니다. 이 모델은 API 설명을 소스 코드처럼 취급하는 팀에 적합합니다: 풀 리퀘스트에서 검토되고, CI에서 게이트 처리되며, 다른 모든 것과 마찬가지로 버전 관리됩니다. OpenAPI Specification은 계약이며, Redocly CLI는 이를 규제하는 도구 체인입니다.

Apidog는 프로젝트 중심적이고 플랫폼 우선입니다. 데스크톱 또는 웹 앱에서 시각적으로 엔드포인트를 설계하고, 목업 서버를 구축하고, 테스트 시나리오를 작성하며, CLI는 그 작업의 하위 집합을 위한 헤드리스(headless) 인터페이스입니다. 대부분의 CLI 명령은 프로젝트 ID로 식별되고 액세스 토큰으로 인증되는 서버의 Apidog 프로젝트에 대해 작동합니다. 사양은 제자리에서 린트하는 느슨한 파일이 아닙니다. 목업, 테스트 및 문서로 게시될 수 있는 살아있는 작업 공간으로 가져옵니다. 하나의 환경, 여러 작업.

어떤 철학도 틀린 것이 아닙니다. 이들은 다른 팀에 적합합니다. 솔직한 차이점은 다음과 같습니다: Redocly는 사양 거버넌스를 위한 집중적이고 오픈 소스 CLI를 제공하며, Apidog는 더 광범위한 플랫폼에 대한 CLI를 제공합니다.

명령별 비교

다음은 작업별로 매핑된 중요한 부분입니다. 아래의 모든 명령은 실제이며, 지어낸 것이 없습니다.

이 중 몇몇 행은 솔직한 설명이 필요합니다. 왜냐하면 차이가 분명하며, 그것 없이는 이 글이 정직하지 못할 것이기 때문입니다.

린팅은 Redocly의 주력 분야이며, Apidog의 주력 분야가 아닙니다. Redocly CLI는 OpenAPI, AsyncAPI, Arazzo, Open-RPC를 구성 가능한 규칙 세트에 대해 린트하며, 자체 규칙을 작성할 수 있습니다. Apidog는 정의를 가져올 때 구조의 유효성을 검사하지만, apidog lint 명령이나 redocly.yaml 스타일의 구성, 또는 CLI를 통해 사용자 정의 스타일 가이드 규칙을 작성하는 방법은 없습니다. 목표가 터미널에서 적용되는 코드 우선 스타일 가이드라면 Redocly가 그 도구입니다. Apidog는 이 분야에서 경쟁하지 않으며, 그렇지 않다고 말하는 것은 잘못된 것입니다.

분할(Split) 및 결합(join)은 Redocly의 기능입니다. redocly split은 하나의 설명을 다중 파일 구조로 분해하고, redocly join(실험적)은 여러 파일을 하나로 병합합니다. Apidog는 이 두 명령을 가지고 있지 않습니다. Apidog의 가져오기는 다중 파일 $ref를 통합된 리소스로 해결하고, 내보내기는 단일 통합 파일을 생성하지만, 이는 느슨한 파일에 대해 실행하는 독립형 분할/결합 유틸리티와는 다릅니다.

테스트 실행 및 목업은 Apidog의 기능입니다. Redocly CLI는 API 테스트를 실행하지 않으며 목업 서버를 호스팅하지 않습니다. 이는 의도적으로 그 범위 밖에 있습니다. Apidog는 apidog run을 사용하여 테스트 시나리오를 헤드리스로 실행하고 파이프라인을 위한 JUnit, HTML, JSON 및 CLI 보고서를 생성하며, 목업은 플랫폼의 주요 기능입니다(앱에서 작성되며 CLI에서 구동되지 않습니다).

두 도구 모두 터미널에서 HTML 문서를 빌드합니다. redocly build-docs는 독립형 Redoc HTML 파일을 생성합니다. apidog export --format html은 프로젝트에서 HTML 문서 파일을 작성합니다. 다른 엔진이지만, 터미널에서 동일한 결과를 제공합니다.

실제 Redocly CLI 명령

전역으로 설치하거나, 설치를 건너뛰고 npx를 통해 실행하십시오:

npm install -g @redocly/cli@latest
# 또는, 전역 설치 없이:
npx @redocly/cli@latest lint openapi.yaml

사양을 린트합니다. redocly.yaml이 있는 경우, 이는 선택한 규칙 세트(minimal, recommended, recommended-strict, spec 또는 사용자 정의 규칙)를 적용합니다:

redocly lint openapi.yaml

이전에 사용되던 swagger-cli가 수행했던 종류의 단순한 구조적 유효성 검사만 원한다면, redocly.yaml을 spec 규칙만으로 구성하고 동일한 redocly lint를 실행하십시오. Redocly는 swagger-cli에서 마이그레이션 가이드를 제공하는데, 이는 Redocly CLI가 swagger-cli의 명명된 후속작이기 때문입니다. swagger-cli 저장소도 동일한 이유로 현재 사용 중단 알림을 포함하고 있습니다. 이 오래된 도구는 스타일 규칙으로 린트하지 않고 유효성 검사 및 번들링만 수행했습니다.

모든 $ref를 따라 다중 파일 정의를 하나의 파일로 번들링합니다:

redocly bundle openapi.yaml --output bundled.json

swagger-cli에서 넘어온 경우, 플래그는 깔끔하게 매핑됩니다: -o/--outfile은 --output이 되고, -t/--type은 --ext(json, yaml 또는 yml)가 되며, -r/--dereference는 -d/--dereferenced가 됩니다.

Redoc으로 독립형 HTML 문서를 빌드합니다:

redocly build-docs openapi.yaml -o docs.html

번들링의 역방향으로, 단일 설명을 다중 파일 레이아웃으로 분할합니다:

redocly split openapi.yaml --outDir ./split-spec

이 범주의 다른 도구들과 Redocly가 어떻게 비교되는지 더 넓게 살펴보려면, OpenAPI linter 설정 가이드에서 Spectral, Redocly, Vacuum을 나란히 다루고 있으며, Redocly 대안 요약에서는 문서 플랫폼을 구체적으로 다룹니다.

실제 Apidog CLI 명령

CLI를 설치하고 앱에서 토큰으로 인증하십시오 (아바타, 계정 설정, API 액세스 토큰):

npm install -g apidog-cli@latest
apidog login --with-token <TOKEN>

토큰은 ~/.apidog/config.toml에 저장됩니다. 출력하거나 커밋하지 마십시오.

프로젝트로 정의를 가져옵니다. 이는 구조의 유효성을 검사하고 다중 파일 $ref를 통합된 리소스로 해결하여 가져옵니다:

apidog import --project 123456 --format openapi --file ./openapi.json

가져오기는 OpenAPI 외에도 Postman, HAR, Insomnia, JMeter, WSDL, YApi, RAP2, apiDoc, Hoppscotch, Markdown, JSON Schema 및 Apidog 자체 형식을 허용합니다.

단일 통합 파일을 내보내고, 선택적으로 OpenAPI 버전을 업그레이드합니다. 이는 번들과 선택적 버전 범프를 한 단계로 수행합니다:

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 run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"

내보낸 컬렉션 파일에서 완전히 오프라인으로 실행할 수도 있으며, 프로젝트나 토큰이 필요하지 않습니다:

apidog run ./collection.apidog-cli.json

--out-dir, -n/--iteration-count, -d/--iteration-data 및 --env-var를 포함한 전체 플래그 참조는 Apidog CLI 전체 가이드에 있습니다. 공식 Apidog CLI 문서는 설치 및 모든 리소스 명령을 다룹니다. 실행기 대 실행기 CI 비교는 Apidog CLI 대 Newman 및 Bruno CLI 대 Apidog CLI를 참조하십시오.

Redocly CLI를 선택해야 할 때

사양이 진실의 원천이고 이를 코드로 관리하고 싶을 때 Redocly CLI를 선택하십시오.

사용자 정의 규칙이 있는 실제 린터가 필요합니다. Redocly의 lint 명령과 redocly.yaml 구성은 대표적인 기능입니다. 내장 규칙 세트를 선택하거나 직접 작성하고, 모든 커밋에서 명명 규칙, 필수 필드 및 사내 스타일을 적용하십시오. Apidog CLI의 어떤 것도 이것과 일치하지 않습니다. 터미널 네이티브 스타일 거버넌스가 필요한 작업이라면 Redocly가 정답입니다.

계정 없이 오픈 소스를 원합니다. CLI는 전적으로 컴퓨터 또는 CI 러너에서 실행됩니다. lint, bundle, split 또는 build-docs에 로그인, 토큰, 서버 호출이 필요 없습니다. 에어갭 환경 또는 엄격한 데이터 처리 규칙의 경우, 이는 Redocly가 충족하고 플랫폼 CLI가 일반적으로 충족하지 못하는 필수 요구 사항입니다.

가볍고 집중적인 도구 체인을 원합니다. 필요한 것이 터미널에서 린트, 번들, 분할, 결합 및 HTML 문서뿐이라면, Redocly는 정확히 그 기능만 수행합니다. 제로 설정으로 설치하거나 npx를 통해 실행할 수 있습니다. 전체 명령 세트는 Redocly CLI 문서 및 npm 패키지 페이지에 있습니다.

Apidog를 선택해야 할 때

사양이 별도의 도구로 조립하고 싶지 않은 더 큰 라이프사이클의 일부일 때 Apidog를 선택하십시오.

하나의 장소에서 디자인, 목업, 테스트 및 문서를 원합니다. CLI는 사양을 가져오고, 선택한 OpenAPI 버전으로 깔끔하게 통합된 파일을 내보내며, CI에서 테스트 시나리오를 실행합니다. 동일한 프로젝트는 시각적 디자인, 목업 서버 및 게시된 문서를 제공하며, 모두 하나의 정의를 공유합니다. 린터, 목업 도구, 테스트 러너 및 문서 생성기를 연결하는 작업을 중단할 수 있습니다.

사용 가능한 보고서와 함께 파이프라인에서 테스트 실행을 원합니다. apidog run은 CI 대시보드를 위한 JUnit XML, HTML 및 JSON 아티팩트를 생성하고, 테스트가 실패하면 0이 아닌 값으로 종료됩니다. Redocly는 테스트를 전혀 실행하지 않으므로, CI 테스트 게이팅이 목록에 있다면 Apidog가 적합합니다. CI의 OpenAPI 유효성 검사 패턴은 동일한 파이프라인에서 테스트 실행과 자연스럽게 연결됩니다.

전체 팀을 위한 하나의 진실의 원천을 원합니다. 리소스는 디자이너, 테스터 및 작가 모두가 작업하는 Apidog 프로젝트에 있습니다. CLI는 공유 작업 공간에 대한 자동화 인터페이스이며, 이는 사양 파일을 주고받는 대신 플랫폼에서 협업하기를 선호하는 팀에 적합합니다.

Apidog 다운로드하여 따라해보십시오. 신용 카드 없이 무료로 시작할 수 있습니다.

상호 보완적일 수 있습니다

이것은 엄격히 양자택일이 아니며, 그렇다고 가정하는 것은 가장 실용적인 설정을 놓치는 것입니다.

강력한 워크플로우는 Redocly CLI (또는 Spectral)를 CI의 린트 게이트로 실행하여 모든 풀 리퀘스트에서 스타일 가이드를 적용하고, Apidog를 디자인, 목업, 테스트 실행 및 게시된 문서에 사용합니다. 터미널에서 오픈 소스 규칙 세트를 사용하여 린트가 가장 잘 작동하는 곳에서 린트합니다. 플랫폼이 가장 잘 작동하는 곳에서 목업, 테스트 및 문서화합니다. 사양은 이들 사이에서 흐릅니다. CI에서 파일을 린트하고, 다운스트림의 모든 작업을 위해 Apidog로 가져옵니다.

이 조합은 각 도구가 다른 도구의 역할을 강요하는 대신 실제 강점을 활용하게 합니다.

FAQ

Apidog CLI에 Redocly처럼 사용자 정의 규칙이 있는 린트 명령이 있습니까?

아니요. Apidog는 정의를 가져올 때 구조의 유효성을 검사하지만, apidog lint 명령이나 CLI를 통해 사용자 정의 스타일 가이드 규칙을 작성하는 방법은 없습니다. 구성 가능하고 코드 우선 린팅을 위해서는 Redocly CLI 또는 Spectral을 사용하십시오.

Redocly CLI가 CI에서 API 테스트를 실행할 수 있습니까?

아니요. Redocly CLI는 린트, 번들, 분할, 결합 및 문서를 빌드합니다. API 테스트를 실행하지 않으며 목업 서버를 호스팅하지 않습니다. JUnit 및 HTML 보고서가 있는 헤드리스 테스트 실행을 위해서는 apidog run을 사용하십시오.

Apidog는 Redocly CLI처럼 오픈 소스입니까?

아니요. Redocly CLI와 Spectral은 오픈 소스입니다. Apidog는 프리미엄입니다. CLI는 npm에서 무료로 설치할 수 있지만, 완전히 오픈 소스 소프트웨어로 작동하기보다는 Apidog 계정 및 프로젝트에 대해 작동합니다.

swagger-cli를 유효성 검사 및 번들에 사용했습니다. 무엇으로 전환해야 합니까?

두 도구 모두 이를 다룹니다. Redocly CLI는 swagger-cli의 명명된 후속작으로, redocly lint(단순 유효성 검사를 위해 spec 규칙 구성) 및 redocly bundle을 제공합니다. Apidog는 apidog import(유효성 검사) 및 apidog export(번들, 선택적 OpenAPI 버전 범프 포함)를 통해 동일한 기능을 제공하며, 동일한 작업 공간에서 목업, 테스트 및 문서를 추가합니다.