손상된 Swagger 파일은 좀처럼 스스로를 알리지 않습니다. YAML은 정상적으로 파싱됩니다. 문서 페이지도 잘 렌더링됩니다. 그러다 프론트엔드 개발자가 여러분의 스펙으로부터 클라이언트를 생성하고, 누락된 required 필드 때문에 빌드가 실패하면, 여러분은 "완성된" API 설명에 `$ref` 오타가 세 커밋 전에 있었다는 것을 알게 됩니다. 스펙은 내내 틀렸던 것입니다. 누군가에게 오후 한나절을 낭비하게 하기 전까지는 아무도 알려주지 않았습니다.
이것이 스웨거 유효성 검사기가 하는 일입니다. 누구든 파일을 사용하기 전에 여러분의 OpenAPI 또는 Swagger 파일을 읽고 문서가 실제로 유효한지 알려줍니다. "보기에 올바른가"가 아니라 "OpenAPI Specification에 부합하고, 모든 참조를 해결하며, 도구가 신뢰할 수 있는 스키마를 설명하는가"를 확인합니다. 유효성 검사기는 조용한 구조적 버그를 시끄러운, 줄 번호가 매겨진 오류로 바꾸어, 몇 시간 동안 하위 시스템을 디버깅하는 대신 몇 초 만에 수정할 수 있게 해줍니다.
Swagger 유효성 검사기가 실제로 확인하는 것
먼저, 명칭에 대해. "Swagger"와 "OpenAPI"는 역사적 시점에 따라 동일한 것을 다르게 설명합니다. 버전 2.0까지는 Swagger라고 불렸고, 이후 OpenAPI Initiative에 기증되어 이름이 변경되었습니다. 3.0, 3.1, 3.2는 모두 OpenAPI입니다. 사람들은 여전히 습관적으로 "스웨거 유효성 검사기"라고 말하며, 대부분의 도구는 Swagger 2.0과 OpenAPI 3.x를 모두 허용합니다. 버전 이력이 모호하다면, Swagger 대 OpenAPI 분석을 통해 명확히 알 수 있습니다. 최신 버전 간의 차이점은 OpenAPI 3.2, 3.1, 3.0에서 변경된 내용을 참조하세요.
진정한 유효성 검사기는 세 가지 작업을 순서대로 수행합니다.
- 파싱. 파일이 유효한 YAML 또는 JSON인가요? 잘못된 탭, 중복된 키, 닫히지 않은 괄호 하나 때문에 문서가 로드되지 않을 수 있습니다. 이것은 가장 저렴하게 잡을 수 있는 오류이자 배포하기 가장 당황스러운 오류입니다.
- 구조 유효성 검사. 문서가 OpenAPI 스키마에 부합하는가요? 모든 작업에는
responses객체가 필요합니다. 모든 매개변수에는in값이 필요합니다. `$ref`는 존재하는 무언가를 가리켜야 합니다. 대부분의 실제 버그가 여기에 숨어 있습니다. - 참조 해결. OpenAPI 문서는 재사용 가능한 스키마를 연결하는 `$ref` 포인터로 가득합니다. 유효성 검사기는 모든 포인터를 따라가서, 대상이 누락되었거나, 스펙이 금지하는 방식으로 순환 참조를 하거나, 잘못된 파일을 가리키는 경우 실패합니다.
이 세 가지를 모두 통과하면 어떤 규격 준수 도구, 코드 생성기, 목 서버, 문서 렌더러도 문제없이 읽을 수 있는 문서가 됩니다. 이 중 하나라도 실패하면, 터미널보다 덜 편리한 곳에서 오류가 나타납니다.
나중에 문제가 되는 오류들
유효성 검사가 추상적으로 느껴질 수 있지만, 이것 없이 어떤 문제가 발생하는지 보면 그렇지 않습니다. 이것들은 편집기에서는 무해해 보이지만 하위 시스템에서 실제 사고로 이어지는 스펙 오류들입니다.
손상된 `$ref` 포인터. 스키마 이름을 User에서 UserProfile로 변경했지만, 응답 본문 깊숙한 곳에 있는 참조 하나를 놓쳤습니다. YAML은 여전히 파싱됩니다. 문서는 페이지의 나머지를 계속 렌더링합니다. 코드 생성기가 이 매달린 포인터를 만나면 누락된 타입의 클라이언트를 생성하거나, 그냥 충돌합니다. 유효성 검사기는 저장하는 즉시 손상된 `$ref`를 표시합니다.
스키마와 예시 불일치. 스키마는 age가 정수라고 하지만, 예시에서는 "age": "thirty"를 보여줍니다. Swagger UI는 둘 다 문제없이 표시합니다. 스펙으로 구축된 목 서버는 소비자가 숫자를 기대하는 곳에 문자열을 반환하고, 세 팀 떨어진 계약 테스트는 아무도 여러분의 파일에서 원인을 찾을 수 없는 이유로 실패합니다.
누락된 필수 요소. responses가 없는 작업. URL 템플릿에 선언되었지만 parameters에 정의되지 않은 경로 매개변수. content가 없는 requestBody. 각각은 기술적으로 잘못된 형식의 문서이며, 어떤 도구가 스펙을 먼저 읽느냐에 따라 다른 하위 시스템 증상을 유발합니다.
타입 및 형식 불일치. 백엔드가 Unix 타임스탬프로 반환하는 필드에 format: date-time이 적용된 경우. 실제로는 배열인데 type: string으로 지정된 경우. 이것들은 구조적 유효성 검사는 통과하지만, 스펙과 실행 중인 API 간의 계약을 위반합니다. 이는 우리가 다룰 별도의 문제입니다.
패턴은 일관적입니다. 스펙 오류는 여러분이 만들 때는 보이지 않지만, 다른 사람이 사용할 때는 큰 비용이 듭니다. 유효성 검사는 이 비용을 저렴한 시점으로 되돌려줍니다.
Swagger 파일을 수동으로 유효성 검사하는 방법
시작하기 위해 플랫폼이 필요하지 않습니다. 오늘 스펙을 빠르게 유효성 검사하는 세 가지 방법이 있습니다.
Swagger 편집기. 여러분의 YAML을 Swagger 편집기에 붙여넣으면, 입력하는 동안 오류를 오른쪽 여백에 줄 번호와 함께 밑줄을 그어 유효성을 검사합니다. 단일 파일을 빠르게 점검하는 가장 빠른 방법이며 무료입니다. 단점은 단일 텍스트 상자라는 것입니다. 문서의 유효성은 검사하지만, 실제 API가 여전히 문서와 일치하는지 여부는 확인하지 않으며, 시각적 스키마 빌더 없이 YAML을 직접 작성해야 합니다. 형식을 배우는 데는 괜찮지만, 팀이 의존하는 스펙의 경우 여러 탭이 필요한 워크플로우 중 하나일 뿐입니다.
Spectral과 같은 린터. Stoplight의 Spectral은 원시적인 유효성을 넘어 스타일 규칙까지 검사하는 오픈소스 CLI입니다. 구조적 유효성을 확인하고, 모든 작업에 설명이 필요하고, 모든 스키마 속성에 타입이 필요하며, 명명 규칙을 따르는 등의 규칙 세트를 적용할 수 있습니다. Spectral은 여러 파일에 걸쳐 스펙 *스타일*을 관리하는 데 있어 진정으로 최고의 도구이며, 일관된 API 디자인이 중요하다면 채택할 가치가 있습니다. 다음과 같이 실행합니다.
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
단점은 범위입니다. Spectral은 문서의 유효성을 검사하고 린트합니다. 이것은 요청 실행기가 아니며, 스펙이 설명하는 API가 실제로 스펙이 주장하는 대로 동작하는지 여부는 알려주지 않습니다. 그것은 다른 계층이며, 대부분의 프로덕션 놀라움이 발생하는 계층입니다.
온라인 유효성 검사기 엔드포인트. Swagger 프로젝트는 호스팅된 스펙 URL에 대한 합격 또는 불합격 배지를 반환하는 유효성 검사 서비스를 제공합니다. README 배지에는 유용하지만, 대화형 수정 루프에는 덜 유용합니다. 독립형 옵션에 대한 더 깊은 내용은 최고의 OpenAPI 유효성 검사 도구 모음과 OpenAPI 스펙 유효성 검사 방법에 대한 집중적인 가이드를 참조하십시오.
이 세 가지 모두 문서의 유효성을 검사합니다. 하지만 유효한 스펙과 올바른 API 사이의 간극을 좁히지는 못합니다. 다음 섹션에서는 바로 이 간극에 대해 다룹니다.
Apidog의 역할: 스펙을 검증하고, API가 스펙과 일치함을 증명하기
Apidog는 올인원 API 플랫폼입니다. 하나의 워크스페이스에서 스키마를 설계하고, 요청을 디버그하고, 자동화된 테스트 시나리오를 구축하고, 목 엔드포인트를 만들고, 문서를 게시할 수 있습니다. 스펙 유효성 검사는 별도로 추가하는 도구가 아니라, 플랫폼 내 작업의 한 속성입니다.
Swagger 또는 OpenAPI 파일을 가져오거나 시각적 편집기에서 설계할 때, Apidog는 가져오는 과정에서 파일을 파싱하고 유효성을 검사합니다. 잘못된 형식의 문서, 손상된 `$ref`, 타입 없는 매개변수 등은 하위 도구에서가 아니라 작업하는 동안 즉시 드러납니다. 편집기가 시각적이기 때문에, 손으로 작성하는 YAML 오류의 전체 범주가 발생하지 않습니다. 필드가 필수 드롭다운일 때 매개변수의 in 값을 잊을 수 없습니다. 스펙은 설계 단계에서부터 유효합니다.
이것은 문서 자체를 처리합니다. 더 어려운 문제는 드리프트(drift)입니다. 즉, 스펙은 한 가지를 말하지만 API는 다른 방식으로 동작하는 점진적인 불일치입니다. 독립형 유효성 검사기는 파일을 유효하다고 판단하기 때문에 이것을 감지할 수 없습니다. 실행 중인 서비스가 잘못된 것입니다. 이것이 수많은 불일치하는 Swagger 문서와 Postman 컬렉션 뒤에 숨겨진 실패 모드입니다.
Apidog는 스펙을 테스트의 단일 정보원으로 만듦으로써 이 문제를 해결합니다. OpenAPI 스펙에서 직접 테스트 시나리오를 생성한 다음, 실제 응답이 선언한 스키마와 일치하는지 확인합니다. 스펙에서 age가 정수라고 말하는데 API가 문자열을 반환하면 테스트는 실패하며, 수동으로 관리되는 사본에 대해서가 아니라 스펙 자체에 대해 실패합니다. 유효성 검사 문제는 "이 파일을 저장했을 때 유효했는가"가 아니라 "지금 라이브 API가 계약에 여전히 충실한가"라는 지속적인 질문이 됩니다. 어설션 메커니즘을 원하시면, API 어설션: 실용 가이드에서 응답 형태, 상태 및 필드 유효성 검사에 대해 다룹니다.
기억하는 대신 유효성 검사를 자동으로 적용하고자 하는 팀을 위해 Apidog는 설계 루프의 일환으로 API가 OpenAPI 표준을 준수하도록 유지하는 기능도 제공합니다.
Apidog CLI를 사용하여 CI에서 스펙 기반 유효성 검사 실행
누군가 편집기를 열 때만 실행되는 유효성 검사기는 결국 건너뛰게 됩니다. 해결책은 유효성 검사를 파이프라인에 넣어 사람이 개입하지 않고 모든 푸시에서 실행되도록 하는 것입니다. 이것이 바로 Apidog 명령줄 실행기가 하는 일입니다.
CLI는 apidog-cli라는 npm 패키지입니다. Node.js가 설치된 모든 환경에서 Apidog로 구축한 테스트 시나리오를 헤드리스 방식으로 실행합니다. 다음 명령으로 설치하십시오.
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을 추가하여 CI 대시보드에 피드할 수 있습니다. --access-token은 CI 비밀 변수에 속하며, 인라인으로 사용해서는 안 됩니다. Apidog 내부의 시나리오 CI/CD 탭에서 토큰과 미리 만들어진 명령을 모두 생성할 수 있습니다. 모든 플래그에 대한 자세한 내용은 apidog run --help를 실행하거나 전체 Apidog CLI 가이드를 참조하십시오.
이것이 진정한 게이트 역할을 하게 하는 세부 사항은 다음과 같습니다. 어설션이 실패하면 CLI는 0이 아닌 종료 코드를 반환합니다. CI 시스템은 이 종료 코드를 읽습니다. 스키마 검사 실패는 단계를 실패시키고, 이는 작업을 실패시키고, 결국 병합을 차단합니다. 따라서 API가 OpenAPI 계약과 일치하지 않는 순간, 변경 사항이 배송되기 전에 빌드가 실패하며, 소비자가 티켓을 제출한 후에야 알게 되는 것이 아닙니다. 이것이 파일을 한 번 유효성 검사하는 것과 모든 커밋에서 계약을 유효성 검사하는 것의 차이입니다. 동일한 종료 코드 동작으로 인해 이 실행기는 Newman 없이 CI에서 Postman 컬렉션 실행과 마찬가지로 모든 CI 플랫폼에 통합될 수 있습니다.
팀이 이미 API를 설계하는 곳에서 스펙 유효성 검사 및 계약 테스트를 원한다면 Apidog를 다운로드하십시오.
실용적인 유효성 검사 워크플로우
이러한 부분들을 종합하여, 마지막 단계뿐만 아니라 모든 단계에서 스펙 오류를 감지하는 순서는 다음과 같습니다.
- 유효성 검사 편집기에서 설계 또는 가져오기. 기존 Swagger 파일을 가져오거나 Apidog의 시각적 디자이너에서 구축하든, 문서는 가져오는 과정에서 파싱되고 구조적으로 유효성이 검사됩니다. 손상된 참조와 누락된 타입은 즉시 드러납니다.
- 규칙 세트가 있다면 스타일 린팅 수행. 조직에서 명명 및 설명 규칙을 강제하는 경우, Spectral을 빠른 사전 커밋 검사로 실행하십시오. 유효성과 내부 스타일은 다른 문제이므로, 둘 다 다루십시오.
- 스펙에서 테스트 생성. OpenAPI 문서를 테스트 시나리오로 전환하여, 여러분의 어설션이 별도의 드리프트될 수 있는 사본이 아닌, 배포하는 동일한 정의에 연결되도록 하십시오.
- CLI로 모든 푸시 게이팅.
apidog run을 파이프라인에 연결하여 스펙과 실제 간의 불일치 시 빌드가 자동으로 실패하도록 하십시오. - 스펙을 단일 정보원으로 간주. 설계가 변경될 때 테스트는 동일한 파일을 가리키므로, 수동으로 동기화할 필요가 없습니다.
1단계와 2단계는 문서를 유효성 검사합니다. 3단계부터 5단계까지는 계약을 유효성 검사합니다. 둘 다 필요하며, 이 모든 것을 수행하는 가장 저렴한 방법은 네 개의 브라우저 탭이 아니라 하나의 워크스페이스에서 하는 것입니다.
간략 버전
스웨거 유효성 검사기는 구조적 버그, 손상된 참조, 누락된 타입, 잘못된 형식의 YAML 등 작성할 때는 보이지 않지만 다른 사람이 읽을 때는 큰 비용이 드는 오류들을 잡아냅니다. 문서 유효성 검사는 최소한의 기준이지 궁극적인 목표가 아닙니다. 실제로 프로덕션에 도달하는 오류는 유효한 스펙이 변경되는 API와 조용히 일치하지 않게 되는 경우이며, 파일 수준의 유효성 검사기는 이러한 오류를 볼 수 없습니다.
해결책은 두 가지 계층에서 유효성 검사를 수행하고 이를 한곳에 두는 것입니다. 즉, 문서를 설계하는 동안 유효성을 검사하고, 모든 푸시에서 실제 응답을 스펙에 대해 어설션하여 계약을 유효성 검사하는 것입니다. Apidog는 첫 번째를 설계 단계에서, 두 번째를 apidog-cli 실행기가 CI에서 게이팅하는 시나리오를 통해 수행합니다. 스펙은 단일 정보원으로 유지되고, 현실이 스펙에서 벗어나는 순간 빌드는 실패하며, 손상된 Swagger 파일은 뒤늦게 발견되는 문제가 아니게 됩니다.