Swagger CLI: 터미널에서 API 스펙 유효성 검사, 린팅 및 테스트

풀 리퀘스트를 열고 문서는 잘 빌드되었지만, 3일 후 동료가 당신에게 연락합니다: 스테이징 서버가 모든 요청을 거부하는데, OpenAPI 파일에 이름을 변경한 경로를 가리키는 ` $ref `가 끊어져 있기 때문입니다. 에디터에서는 스펙이 올바르게 보였고, Swagger UI에서도 잘 렌더링되었습니다. 하지만 실제로는 유효하지 않았고, 배포되기 전까지 파이프라인에서 아무것도 잡아내지 못했습니다.

이것이 바로 Swagger 명령줄 도구가 만들어진 정확한 목적입니다: 사람이 발견하기 전에 손상된 스펙을 찾아내는 것입니다. "swagger cli"라는 문구는 일반적으로 @apidevtools/swagger-cli를 가리키는데, 이는 OpenAPI 문서를 확인하고 여러 파일로 된 스펙을 하나로 묶는 두 가지 명령(validate와 bundle)을 가진 작은 npm 패키지입니다. 이 도구는 정말 유용하며, 이 가이드에서는 이를 올바르게 사용하는 방법을 보여줍니다. 또한 스펙 유효성 검사가 API를 신뢰하는 것의 절반에 불과하기 때문에 이 도구가 멈추는 지점도 보여줍니다. 나머지 절반은 실제 요청을 보내고 반환되는 내용에 대해 단언하는 것이며, 이때 Apidog CLI와 같은 러너가 역할을 이어받습니다.

따라서 이것은 실제로 두 터미널 작업에 해당합니다. 먼저, swagger-cli(또는 그 후속 도구)로 스펙을 린트하고 번들하여 계약이 견고한지 확인합니다. 그런 다음 명령줄에서 실행 중인 API에 대해 실제 테스트를 실행하여 구현이 계약과 일치하는지 확인합니다. 우리는 이 두 가지를 모두 다루고, 어떤 도구가 어떤 작업을 담당하는지 솔직하게 밝히며, 각각에 대한 복사-붙여넣기 명령을 제공할 것입니다.

"swagger cli"가 실제로 가리키는 것

“swagger”라고 불리는 단일 공식 바이너리는 없습니다. 이 이름은 몇 가지 다른 도구들을 지칭하며, 어떤 것을 의미하는지 아는 것이 많은 혼란을 줄여줍니다.

• @apidevtools/swagger-cli는 대부분의 사람들이 의미하는 패키지입니다. 그 바이너리는 swagger-cli이며, 두 가지 작업을 수행합니다: OpenAPI 또는 Swagger 2.0 문서의 유효성을 검사하고, 여러 파일로 구성된 스펙을 하나의 파일로 번들합니다. 이 글의 전반부에서 중점적으로 다룰 내용입니다.
• swagger-codegen은 스펙에서 클라이언트 SDK와 서버 스텁을 생성하는 별도의 훨씬 더 큰 SmartBear 프로젝트입니다. 완전히 다른 작업이며, 글의 마지막 부분에서 다룰 것입니다.
• Swagger UI와 Swagger Editor는 CLI가 전혀 아닙니다. 브라우저에서 스펙을 렌더링하고 편집합니다. 아직 이 형식을 배우는 중이라면, Swagger 및 OpenAPI 입문서가 올바른 시작점입니다.

이 가이드는 명령줄 작업, 즉 유효성 검사, 번들링, 린팅, 그리고 테스트에 관한 것입니다. 대신 설계 및 테스트 플랫폼에 대한 더 넓은 조사를 원한다면, Swagger 대안 종합에서 GUI 측면을 다룹니다.

swagger-cli 설치

이 도구는 npm 패키지로 제공됩니다. 전역으로 설치하세요:

npm install -g @apidevtools/swagger-cli

설치 확인:

swagger-cli --version
swagger-cli --help

Node.js가 유일한 시스템 종속성입니다. Node가 이미 설치된 모든 머신이나 CI 이미지에서 실행할 수 있습니다. 전역으로 설치하고 싶지 않다면, 임시 빌드 러너에서 유용한 npx @apidevtools/swagger-cli ...를 사용하여 필요할 때 호출할 수 있습니다.

이것을 사용하기 전에 알아야 할 한 가지는 유지보수 담당자들이 swagger-cli를 사용 중단(deprecated)으로 표시했다는 것입니다. README는 적은 기여자 수에 비해 많은 사용자 기반의 유지보수 부담을 언급하며 이를 분명히 밝히고 있습니다. 여전히 작동하며, 오늘날 많은 파이프라인에서 실행되고 있지만, 새로운 프로젝트는 활발하게 유지보수되는 후속 도구인 Redocly CLI를 지향하고 있습니다. 우리는 아래 섹션에서 이 마이그레이션을 다룰 것이므로, 충분한 정보를 가지고 결정할 수 있습니다.

swagger-cli로 스펙 유효성 검사하기

핵심 명령은 validate입니다. 스펙 파일을 지정하세요:

swagger-cli validate openapi.yaml

문서가 올바르면, 한 줄 확인 메시지와 종료 코드 0을 받습니다. 문제가 있으면, 문제 설명과 0이 아닌 종료 코드를 받게 되는데, 이는 파이프라인에서 정확히 원하는 결과입니다.

validate는 내부적으로 두 가지 검사를 실행하며, 이 중 하나를 끌 수 있습니다:

swagger-cli validate --no-schema openapi.yaml
swagger-cli validate --no-spec openapi.yaml

--no-schema는 OpenAPI JSON 스키마에 대한 유효성 검사를 건너뜁니다. 이는 문서가 올바른 형태를 가지고 있는지 확인하는 구조적 검사입니다. --no-spec은 사양 규칙 자체에 대한 유효성 검사를 건너뜀니다. 이는 중복된 operation ID나 아무데도 가리키지 않는 $ref와 같은 문제를 잡아내는 의미론적 검사입니다. 대부분의 경우 두 가지 모두 켜두는 것이 기본 설정입니다. 이 플래그는 특정 계층에서 의도적으로 허용해야 하는 문제를 표시하는 드문 경우를 위해 존재합니다.

validate가 잘 잡아내는 것: 잘못 구성된 YAML, 누락된 필수 필드, 손상된 $ref 포인터, 그리고 스펙을 파싱할 수 없게 만드는 구조적 오류. validate가 하지 않는 것은 팀의 스타일을 강제하는 것입니다. 설명이 없고, 일관성 없는 이름 지정, 그리고 예시가 없는 스펙도 OpenAPI 규칙을 위반하지 않기 때문에 아무 문제 없이 통과시킵니다. 이러한 종류의 주관적인 검사를 위해서는 린터가 필요하며, 이는 다음 섹션에서 다룰 것입니다.

만약 유효성 검사만이 이 글을 읽는 목적이라면, OpenAPI 스펙 유효성 검사 방법에 대한 더 심층적인 내용은 알아둘 가치가 있는 여러 도구와 예외 사례를 비교합니다.

다중 파일 스펙 번들링

실제 스펙은 거의 단일 파일에 존재하지 않습니다. 스키마를 components/ 디렉토리로 분할하고, $ref로 참조하며, 루트 파일을 읽기 쉽게 유지합니다. 이것은 좋은 관행이지만, 많은 다운스트림 도구들은 단일의 독립적인 문서를 원합니다. bundle 명령은 트리를 평탄화합니다:

swagger-cli bundle openapi.yaml -o dist/openapi.bundled.yaml -t yaml

알아둘 가치가 있는 플래그:

• -o, --outfile <file>는 결과를 표준 출력 대신 파일에 씁니다.
• -t, --type <json|yaml>은 출력 형식을 설정합니다. 기본값은 json이므로 YAML로 출력하고 싶다면 -t yaml을 전달하세요.
• -r, --dereference는 외부 파일을 하나의 문서로 모으는 대신 모든 $ref를 완전히 인라인합니다. 이로 인해 남은 참조가 없는 더 큰 파일이 생성되며, 일부 소비자가 이를 요구합니다.
• -f, --format <spaces>는 들여쓰기를 제어하며, 기본값은 2칸입니다.
• -w, --wrap <column>은 긴 YAML 문자열을 줄 바꿈할 때의 줄 길이를 설정합니다.

일반 번들과 --dereference의 차이는 중요합니다. 일반 번들은 내부 $ref 포인터를 유지하지만 모든 개별 파일을 하나로 모아서 문서의 이식성을 높입니다. --dereference는 모든 참조를 인라인 객체로 해결하여 파일 크기를 크게 만들지만, 소비자가 포인터를 해결할 필요가 없도록 보장합니다. 배포용으로는 일반 번들을 사용하고, 특정 도구가 요구할 때만 역참조된 형태를 사용하세요.

일반적인 패턴은 빌드의 일부로 한 단계에서 유효성을 검사하고 번들링하는 것입니다:

swagger-cli validate openapi.yaml && swagger-cli bundle openapi.yaml -o dist/openapi.json

&&는 유효성 검사가 통과해야만 번들링이 실행됨을 의미하므로, 손상된 스펙은 빌드 아티팩트를 생성하지 않습니다.

CI에 swagger-cli 통합하기

유효성 검사는 누군가 기억할 때가 아니라 모든 변경 사항에 대해 실행될 때 가장 가치가 있습니다. 이를 빠른 게이트로 파이프라인에 포함시키세요. 다음은 잘못된 스펙에서 빌드를 실패시키는 GitHub Actions 단계입니다:

name: Validate OpenAPI spec

on:
  pull_request:
    paths:
      - 'openapi.yaml'
      - 'components/**'

jobs:
  validate-spec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Validate spec
        run: npx @apidevtools/swagger-cli validate openapi.yaml

swagger-cli validate는 잘못된 스펙에서 0이 아닌 값으로 종료되므로, 해당 단계는 빨간색으로 표시되고 풀 리퀘스트에는 실패한 검사가 나타납니다. 추가 구성은 필요 없습니다. paths 필터는 스펙이 변경되지 않았을 때 작업이 실행되는 것을 방지하여 CI 시간을 절약합니다.

이것은 API 리포지토리에 추가할 수 있는 가장 저렴한 품질 게이트입니다. 몇 초밖에 걸리지 않으며 "문서가 거짓말했다"라는 종류의 버그가 다운스트림에 도달하는 것을 완전히 막아줍니다.

유효성 검사뿐만 아니라 린팅이 필요할 때

유효성 검사는 한 가지 질문에 답합니다: 이것이 유효한 OpenAPI 문서인가? 린팅은 더 어려운 질문에 답합니다: 이것이 우리 팀의 표준에 부합하는 좋은 OpenAPI 문서인가? 이 둘은 같지 않으며, swagger-cli는 첫 번째만 수행합니다.

예를 들어, 팀의 스타일 가이드가 모든 작업에 summary를, 모든 속성에 description을, 그리고 모든 경로에 kebab-case를 사용하도록 요구한다고 가정해 봅시다. 스펙은 이 세 가지를 모두 위반하더라도 swagger-cli validate를 통과할 수 있습니다. 이러한 규칙은 OpenAPI 사양의 일부가 아니기 때문입니다. 린터는 이러한 규칙을 인코딩하고 강제할 수 있도록 해줍니다.

이것이 팀들이 swagger-cli 자체가 지향하는 유지보수되는 후속 도구인 Redocly CLI로 전환하는 주된 이유입니다. Redocly CLI는 동일한 유효성 검사 및 번들링 기능을 제공하며, 그 위에 실제 린팅 엔진을 추가합니다.

Redocly CLI로 마이그레이션하기

명령어 이름이 비슷하기 때문에 마이그레이션은 간단합니다. 후속 도구를 설치하세요:

npm install -g @redocly/cli

유효성 검사에 해당하는 것은 lint입니다. 이전 동작과 최대한 가깝게 맞추려면 최소 규칙 세트를 확장하세요:

redocly lint --extends=minimal openapi.yaml

대신 기본 규칙 세트로 실행하면 더 강력한 권장 규칙 세트가 강제 적용되며, 여기서 린팅의 가치가 나타납니다. redocly.yaml 파일에서 규칙을 구성하고, 각 규칙을 error 또는 warn으로 설정하며, 조직별 검사를 위한 사용자 지정 플러그인도 작성할 수 있습니다.

번들링은 거의 일대일로 매핑됩니다:

redocly bundle openapi.yaml -o dist/openapi.yaml

플래그 이름이 약간 변경됩니다. swagger-cli의 -o/--outfile은 --output으로, -t/--type은 --ext로, 그리고 -r/--dereference는 -d/--dereferenced로 바뀝니다. 이전 스크립트에서 짧은 플래그를 사용했다면, 빠르게 찾아서 바꾸는 것으로 충분합니다. 스펙 검사 도구에 대한 더 넓은 비교를 원한다면, 최고의 OpenAPI 유효성 검사 도구 분석에서 Redocly를 다른 대안들과 비교하고 있습니다.

요약하자면: 새로 시작한다면 Redocly CLI를 사용하는 것이 좋습니다. 기존의 swagger-cli 단계가 잘 작동하고 있다면 당장 큰 문제는 없지만, 앞으로 나아갈 방향은 명확하며 이름 변경은 기계적인 작업입니다.

스펙 도구가 다룰 수 없는 절반

지금까지 논의한 모든 도구의 한계는 여기에 있습니다. swagger-cli validate는 스펙이 잘 구성되어 있는지 확인합니다. redocly lint는 스펙이 스타일을 따르는지 확인합니다. 둘 다 실행 중인 API에 단 하나의 요청도 보내지 않습니다. 스펙은 서류상 완벽할 수 있지만, 실제 구현에서는 500 오류를 반환하거나, 약속했던 필드를 생략하거나, 쿼리 매개변수를 완전히 무시할 수 있습니다.

이 간극을 메우는 것은 기능 테스트를 의미합니다: 실제 엔드포인트에 실제 요청을 보내고, 상태 코드, 응답 본문, 그리고 그 안의 값들을 단언(assert)하는 것입니다. 이것은 다른 범주의 도구이며, Apidog가 워크플로우에 적합한 지점입니다.

Apidog는 올인원 API 플랫폼입니다. OpenAPI 스펙을 가져오면, 그 하나의 정의에서 인터랙티브 문서, 모의 서버, 그리고 단언을 통해 연결할 수 있는 테스트 시나리오를 작업 공간을 떠나지 않고도 얻을 수 있습니다. 가져오기는 직접적입니다. Swagger 또는 OpenAPI를 가져와 실행 가능한 요청 생성하기 가이드에서 그 방법을 설명하며, 수동으로 구축하는 대신 스펙에서 직접 전체 테스트 컬렉션을 생성할 수 있습니다.

터미널에 중요한 부분은 apidog-cli npm 패키지로 게시된 명령줄 러너입니다. 이를 설치하고 저장된 시나리오를 헤드리스 모드로 실행합니다:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

-t 플래그는 테스트 시나리오 ID이며, -e는 환경 ID이고, -r은 cli, html, json, junit와 같은 보고서 형식을 선택합니다. swagger-cli처럼 깔끔한 상태 코드로 종료되므로, 실패한 단언은 파이프라인을 빨간색으로 만듭니다. swagger-cli와 달리, 이것이 확인하는 것은 API의 실제 동작이며, 단순히 API를 설명하는 파일의 형태가 아닙니다. 전체 플래그 참조 및 CI 예시는 Apidog CLI 전체 가이드를 참조하거나, 현재 옵션을 보려면 apidog run --help를 실행하세요. 첫 번째 시나리오를 설정하고 싶다면, Apidog를 다운로드하고 스펙을 가져온 다음, 시나리오의 CI/CD 탭에서 러너 명령을 복사하면 됩니다.

완벽한 터미널 워크플로우

두 부분을 함께 합치면 계약과 구현을 순서대로 확인하는 파이프라인을 얻을 수 있습니다:

# 1. 스펙이 잘 구성되어 있고 스타일에 맞는지?
redocly lint --extends=minimal openapi.yaml

# 2. 단일 배포 가능한 문서를 생성합니다.
redocly bundle openapi.yaml -o dist/openapi.yaml

# 3. 실행 중인 API가 실제로 계약과 일치하는지?
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit

첫 번째 단계는 잘못 구성되거나 스타일에 맞지 않는 스펙에서 빠르게 실패합니다. 두 번째 단계는 문서와 SDK 생성기가 사용하는 아티팩트를 생성합니다. 세 번째 단계는 실제 트래픽을 보내고 응답을 단언하므로, 빌드가 성공(녹색)했다는 것은 계약과 그 뒤에 있는 코드 모두 건전하다는 것을 의미합니다. 각 단계는 실패 시 0이 아닌 값으로 종료되므로, 전체 체인은 Node가 있는 모든 CI 러너에 포함할 수 있는 단일 게이트 역할을 합니다.

오늘날 테스트가 조용해진 스펙 준수 도구에 의존하고 있다면, Dredd 없이 API를 스펙에 대해 유효성 검사하기에 대한 글은 동일한 계약 대 구현 아이디어를 다른 관점에서 다룹니다.

swagger-codegen에 대한 참고

“swagger cli”를 검색하는 사람들은 때때로 실제로 다른 작업을 하는 다른 도구인 swagger-codegen을 원하는 경우도 있습니다. 이는 OpenAPI 스펙을 읽어 수십 가지 언어로 클라이언트 SDK, 서버 스텁 및 문서를 생성합니다. 게시된 스펙에서 타입이 지정된 클라이언트를 부트스트랩하는 데 정말 유용하며, Swagger 계열에서 가장 유능한 코드 생성 옵션이라고 할 수 있습니다.

이것은 이 글에서 다루는 의미에서의 유효성 검사, 린트 또는 테스트를 수행하지 않습니다. 생성은 이미 견고한 스펙이 있다고 가정합니다. 입력이 손상되면 출력도 그에 맞춰 손상됩니다. 따라서 코드 생성 워크플로우에서도 그 앞에 유효성 검사 또는 린트 단계를 두는 것이 좋습니다. 이 도구들은 서로를 대체하기보다는 보완합니다.