만약 파이프라인에서 여전히 swagger-cli validate와 swagger-cli bundle을 실행하고 있다면, 더 이상 아무도 관리하지 않는 도구를 중심으로 스크립트를 유지하고 있는 것입니다. swagger-cli GitHub 저장소는 이제 직접적으로 이렇게 말합니다: 이 패키지는 더 이상 유지보수되지 않으며, README는 기여는 거의 없이 방대한 사용자층을 따라잡아야 하는 부담을 언급하고, 새로운 사용자들을 다른 곳으로 안내합니다.
따라서 지금은 스펙 워크플로우를 어디로 옮길지 결정하기에 좋은 시점입니다. 이 가이드는 사용법 튜토리얼이 아니라 마이그레이션 런북입니다. 아직 옮길 준비가 되지 않았고 단순히 오래된 도구를 계속 사용하고 싶다면, Swagger CLI 가이드에서 validate와 bundle에 대해 자세히 다룹니다. 이 글은 Swagger CLI를 Apidog CLI로 마이그레이션하면서 CI를 중단시키지 않는 방법에 대해 구체적으로 설명합니다.
실제 명령어를 따라하고 싶다면 Apidog를 다운로드하세요. 시작은 무료이며, 신용카드가 필요 없습니다.
지금 마이그레이션해야 하는 이유
솔직한 답변부터 하자면: swagger-cli는 한동안 사용 중단되고 유지보수되지 않았습니다. 여전히 실행은 됩니다. 오늘날에도 많은 파이프라인이 이를 호출합니다. 하지만 버그 수정이나 스펙 업데이트를 받지 못하는 도구는 빌드에 기술적 부채로 남아 있으며, 유지보수 담당자들 스스로 다른 도구로 넘어갈 것을 권장합니다.
그들은 특히 한 가지 후속 도구를 지목합니다. 터미널에서 validate와 bundle만을 원했다면 Redocly CLI가 가장 가까운 드롭인 대체재입니다. 이는 오픈 소스이고, 코드 우선이며, 터미널 네이티브입니다. lint 명령어는 구조적 유효성 검사를 수행하며, redocly bundle은 swagger-cli bundle과 정확히 동일하게 $ref 포인터를 따릅니다. 스펙을 저장소에 단일 파일로 유지하는 1:1 교체가 유일한 목표라면 Redocly가 자연스러운 선택이며, Redocly는 명령어 매핑이 포함된 자체 마이그레이션 가이드를 발행합니다. 이 경로를 택하는 것은 부끄러운 일이 아닙니다.
Apidog는 다른 목표를 가지고 있습니다. 스펙이 파일에 머무는 것 이상을 하기를 원할 때 Apidog CLI로 마이그레이션하세요. 정적 문서를 검증하고 번들링하는 대신, 전체 정의를 활성 작업 공간으로 가져와 가져올 때 유효성을 검사하고, 필요할 때 통합 파일을 내보내고, 선택적으로 API를 모의(mock)하고, 이에 대해 테스트 시나리오를 실행하고, 동일한 소스에서 문서를 게시할 수 있습니다. swagger-cli는 두 가지 작업만 수행했습니다. Apidog는 나머지 수명 주기를 모두 다룹니다.
과장된 광고가 아니라 적합성을 기준으로 선택하세요. 터미널에서만 실행하는 경량의, 설정 기반 린터(linter)와 번들러(bundler)를 원한다면 Redocly가 좋습니다. 여러 도구를 함께 연결하는 대신 설계, 모의(mocking), 테스트 및 문서를 위한 단일 플랫폼을 원한다면 Apidog가 좋습니다.
swagger-cli가 했던 일 vs Apidog CLI가 하는 일
swagger-cli에는 정확히 두 가지 명령어가 있었습니다:
swagger-cli validate <file>은 Swagger 2.0 또는 OpenAPI 3.0 문서를 스키마에 대해 확인하고$ref포인터가 해결되는지 검증했습니다.swagger-cli bundle <file>은 해당$ref포인터를 따르고 여러 파일로 된 정의를 단일 파일로 결합했으며, 출력 경로(-o), 유형(-t json|yaml), 전체 역참조(-r), 들여쓰기(-f) 옵션을 제공했습니다.
이것이 도구의 전부였습니다. 스타일 규칙으로 린트(lint)를 하거나, 문서를 생성하거나, 테스트를 실행하거나, 어떤 것도 모의(mock)하지 않았습니다.
Apidog CLI는 이 두 가지 작업을 두 가지 명령어로 매핑한 다음, 더 많은 기능을 제공합니다:
apidog import는 정의를 Apidog 프로젝트로 가져오고 가져오는 과정에서 유효성을 검사합니다. 다중 파일 스펙은$ref포인터가 자동으로 통합 리소스로 해결됩니다. 이것은 유효성 검사 단계와 가져오기를 포함합니다.apidog export는 프로젝트에서 단일 통합 파일을 내보내고, 내보낼 때 OpenAPI 버전을 선택할 수 있게 합니다. 이것은 번들 단계와 선택적 버전 업그레이드, 그리고 HTML 또는 Markdown 문서를 내보내는 기능을 포함합니다.apidog run은 CI를 위한 JUnit 및 기타 리포터를 사용하여 테스트 시나리오 및 스위트를 실행합니다. swagger-cli에는 해당 기능이 없었습니다.- 리소스 명령어(
endpoint,schema,mock,environment,branch등)는 스펙이 일단 들어가면 터미널에서 프로젝트를 관리합니다.
매핑을 정직하게 유지하기 위한 한 가지 정확한 요점: Apidog는 가져올 때 구조를 검증하지만, 구성 가능한 스타일 가이드 린터는 아닙니다. apidog lint 명령어와 사용자 지정 규칙 세트는 없습니다. 만약 독자적인 린팅(linting)에 의존했다면, 그 부분은 그대로 적용되지 않으며, validate 및 bundle을 넘어 얻는 것 섹션에서 이를 처리하는 방법을 다룹니다.
설치 및 로그인
Apidog CLI는 npm 패키지로 제공됩니다. 전역으로 설치하세요:
npm install -g apidog-cli@latest
그런 다음 액세스 토큰으로 인증하세요:
apidog login --with-token <TOKEN>
토큰은 Apidog 앱 또는 웹에서 얻을 수 있습니다: 아바타를 클릭하고, 계정 설정으로 이동한 다음, API 액세스 토큰에서 하나를 생성하세요. CLI는 이를 ~/.apidog/config.toml에 저장합니다. 다른 비밀 정보처럼 다루세요. 로그에 출력하거나 저장소에 커밋하지 마세요.
모든 플래그와 더 심층적인 사용법을 원한다면, Apidog CLI 완전 가이드와 공식 Apidog CLI 문서에서 모든 내용을 다룹니다. 이 마이그레이션에서는 설치 및 로그인만으로 시작할 수 있습니다.
명령어 매핑 테이블
다음은 swagger-cli에서 Apidog CLI로의 직접적인 변환입니다. 한 가지 구조적 차이점은: Apidog는 프로젝트를 기반으로 작동하므로, 대부분의 워크플로우는 단일 파일에 대한 단일 명령보다는 가져오기-내보내기 방식입니다.
| swagger-cli 명령어 | Apidog CLI 대응 명령어 | 변경 사항 |
|---|---|---|
swagger-cli validate openapi.yaml |
apidog import --project <id> --format openapi --file ./openapi.yaml |
가져오기 시 스펙 유효성 검사; 유효하지 않은 스펙은 명령어 실패 |
swagger-cli bundle openapi.yaml -o out.json |
apidog import ... 후 apidog export --project <id> --format openapi --output ./out.json |
번들링이 프로젝트에서 내보내기로 변경; $refs는 가져오기 시 이미 해결됨 |
swagger-cli bundle -t yaml |
apidog export --project <id> --format openapi --output ./out.yaml |
출력 형식은 작성하는 파일을 따름 |
| (해당 없음) | apidog export --project <id> --format openapi --output ./out.json --oas-version 3.1 |
2.0 또는 3.0 스펙을 내보내기 시 3.1로 업그레이드 |
| (해당 없음) | apidog export --project <id> --format html --output ./docs.html |
독립형 HTML 문서 내보내기 |
| (해당 없음) | apidog export --project <id> --format markdown --output ./docs.md |
Markdown 문서 내보내기 |
| (해당 없음) | apidog run --project <id> -t <scenarioId> -e <envId> -r junit |
CI에서 API 테스트 실행 |
마이그레이션에 가장 중요한 두 칸은 첫 두 줄입니다. 그 아래의 모든 것은 swagger-cli가 결코 가지지 못했던 기능입니다. --oas-version 플래그는 가장 명확한 업그레이드입니다: swagger-cli는 Swagger 2.0 파일을 번들링할 수 있었지만, 이를 OpenAPI 3.1로 변환할 수는 없었습니다. Apidog는 내보내기 시에 이를 수행할 수 있으며, 이는 오래된 계약을 현대화할 때 유용합니다. 특히 문서 출력이 목표라면, OpenAPI를 Markdown으로 내보내기 가이드에서 해당 형식을 더 자세히 다룹니다.
단계별 마이그레이션
다음은 swagger-cli 설정에서 작동하는 Apidog 워크플로우로 가는 전체 경로입니다.
1. 프로젝트 ID를 얻으세요. Apidog 앱에서 프로젝트를 생성하거나 엽니다. 프로젝트 ID는 프로젝트 설정 및 URL에 표시됩니다. 모든 CLI 명령어에 --project를 통해 전달할 것입니다.
2. 루트 스펙을 가져오세요. 정의의 진입 파일(entry file)을 Apidog에 지정합니다. $ref 포인터가 있는 다중 파일 스펙은 자동으로 해결되므로, 루트를 가져오면 Apidog가 나머지를 가져옵니다:
apidog import --project 123456 --format openapi --file ./openapi.yaml
스펙이 잘못되었거나 $ref가 제대로 연결되지 않으면 가져오기가 실패합니다. 이 실패는 유효성 검사 게이트 역할을 하며, swagger-cli validate가 수행했던 것과 동일한 작업이 이제 가져오기(ingestion)에 통합되었습니다.
3. 앱에서 확인하세요. 프로젝트를 열고 엔드포인트, 스키마 및 매개변수가 올바르게 로드되었는지 확인합니다. 이 시각적 확인은 swagger-cli에 해당하는 기능이 없으며, 가져오기가 예상대로 작동했는지 확인하기 위해 마이그레이션 중에 한 번 수행할 가치가 있습니다.
4. 통합 파일을 내보내세요. 단일 평면 파일(하위 도구, 클라이언트 생성기 또는 아티팩트용)이 필요할 때 내보냅니다. 원하는 OpenAPI 버전을 선택하세요:
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
이것은 swagger-cli bundle을 대체합니다. $ref 포인터는 가져올 때 이미 해결되었으므로, 내보내기는 통합된 단일 파일 출력입니다.
5. CI에 연결하세요. 기존 swagger-cli 단계를 가져오기(가져오기 시 유효성 검사) 및 내보내기(번들)로 바꾸고, 시나리오가 있다면 테스트 실행을 추가하세요. 다음 섹션에 완전한 GitHub Actions 예시가 있습니다.
GitHub Actions를 사용한 CI 예시
이 워크플로우는 CLI를 설치하고, 저장소 비밀(repo secrets)의 토큰으로 로그인하며, 스펙을 가져와 유효성을 검사하고, 통합 아티팩트를 내보낸 다음, JUnit 리포터로 테스트 시나리오를 실행하여 테스트 실패 시 검사를 실패하고 PR을 게이트합니다.
name: API spec check
on:
pull_request:
branches: [main]
jobs:
apidog:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Apidog CLI
run: npm install -g apidog-cli@latest
- name: Log in
run: apidog login --with-token ${{ secrets.APIDOG_ACCESS_TOKEN }}
- name: Import spec (validates on import)
run: apidog import --project 123456 --format openapi --file ./openapi.yaml
- name: Export consolidated spec
run: apidog export --project 123456 --format openapi --output ./dist/openapi.json --oas-version 3.1
- name: Run test scenarios
run: apidog run --project 123456 -t 7890 -e 4567 -r "cli,junit" --out-dir ./reports
토큰이 로그에 나타나지 않도록 APIDOG_ACCESS_TOKEN으로 저장소 비밀에 저장하세요. -r "cli,junit" 리포터는 CI가 테스트 보고서로 표시할 수 있는 JUnit XML 파일을 작성하며, 실패하는 시나리오는 병합을 차단하는 0이 아닌 종료 코드를 반환합니다. 더 심층적인 파이프라인 패턴에 대해서는 Apidog CLI CI/CD 가이드를 참조하고, 러너별 설정에 대해서는 GitHub Actions와 함께 Apidog CLI 가이드를 참조하세요.
validate 및 bundle을 넘어 얻는 것
이것이 마이그레이션이 보상을 얻는 지점이며, 정직함이 가장 중요한 부분입니다.
모의(Mock) 서버. 스펙이 프로젝트에 있으면, Apidog는 이를 통해 모의 응답을 제공할 수 있습니다. 백엔드가 존재하기 전에 API에 대한 프론트엔드를 개발할 수 있습니다. swagger-cli는 런타임 동작을 건드리지 않았습니다.
자동화된 테스트 시나리오. apidog run은 실행 중인 API에 대해 실제 요청을 실행하고 응답을 확인합니다. 앱에서 시나리오를 시각적으로 구축한 다음, CI에서 헤드리스(headless)로 실행합니다. 이는 swagger-cli가 크게 벌려놓았던 격차를 메웁니다: 유효한 스펙은 계약이 잘 구성되어 있음을 알려주지만, 구현이 스펙과 일치하는지는 알려주지 않습니다.
호스팅되고 내보내진 문서. apidog export --format html 또는 --format markdown은 동일한 소스에서 직접 문서를 생성합니다. 별도의 문서 빌드 단계를 유지할 필요가 없습니다.
이제 솔직한 한계입니다. Apidog CLI에는 사용자 지정 규칙 세트를 갖춘 구성 가능한 코드 우선 스타일 가이드 린터가 없습니다. 가져올 때 구조를 검증하지만, CLI를 통해 Spectral 스타일 또는 Redocly 스타일 규칙을 작성할 수 없으며, apidog lint 명령어는 없습니다. 만약 기존 설정이 강력한 린팅(일관된 명명, 필수 설명, 모든 응답에 대한 예시)에 의존했다면, 전용 린터를 계속 사용하세요. 이를 위해 Apidog를 Spectral 또는 Redocly와 함께 사용하고, 이를 별도의 CI 단계로 실행하세요. OpenAPI 린터 설정 가이드에서 이를 연결하는 방법을 다룹니다. 둘을 함께 사용하는 것이 모순은 아닙니다: 전문 도구로 린트를 수행한 다음, Apidog에서 수명 주기를 관리하세요.