OpenAPI 사양은 계약서입니다. 코드 생성기는 이를 읽고, 문서는 이를 기반으로 만들어지며, 목 서버는 이를 통해 실행되고, 클라이언트 SDK가 이를 통해 생성됩니다. 사양이 잘못되면 모든 하위 아티팩트가 오류를 상속받습니다. 검증기는 문제가 확산되기 전에 사양 파일에서 문제를 잡아냅니다.
이 요약은 사용할 가치가 있는 OpenAPI 검증 도구, 각 도구의 장점, 그리고 실제 워크플로에 어떻게 적용되는지 다룹니다. 일부는 원시 구문을 확인합니다. 다른 일부는 스타일 및 디자인 규칙을 강제합니다. 최적의 설정은 일반적으로 이 두 가지를 결합하며, 이 가이드는 이를 조합하는 방법을 설명합니다.
사양 검증이 중요한 이유
검증기가 해결하는 두 가지 별개의 문제가 있으며, 이들을 혼동하면 혼란이 초래됩니다.
첫 번째는 정확성입니다. 파일이 OpenAPI로 유효한가요? 잘못 들여쓰기된 YAML 블록, 아무것도 가리키지 않는 $ref, 필수 description이 누락된 응답, 타입 이름에 오타가 있는 스키마 등이 있습니다. 이는 객관적인 오류입니다. 파일은 OpenAPI 스키마에 따라 구문 분석되거나 그렇지 않습니다. 정확성 검증기는 '예' 또는 '아니오'로 답을 줍니다.
두 번째는 품질입니다. 사양은 유효하지만, 좋은 사양일까요? 모든 작업은 요약을 가져야 합니다. 경로 이름은 일관되어야 합니다. 모든 오류 응답은 문서화되어야 합니다. 보안은 선언되어야 합니다. 이들 중 어느 것도 OpenAPI 스키마에서 필수는 아니지만, 이를 건너뛰면 기술적으로는 유효하지만 사용하기 어려운 사양이 만들어집니다. 린터는 이러한 디자인 규칙을 강제합니다. 이 두 가지 종류의 문제를 SDK가 출시된 후에 잡는 것보다 일찍 잡는 것이 훨씬 저렴하며, 이는 더 넓게는 API 계약 테스트의 논리와 동일합니다.
알아둘 가치가 있는 검증 도구
Swagger Editor
Swagger Editor는 OpenAPI 프로젝트의 공식 브라우저 기반 편집기입니다. 왼쪽에 사양을 붙여넣거나 작성하면 오른쪽에 유효성 검사 오류와 렌더링된 미리보기를 실시간으로 볼 수 있습니다. 설정 없이 사양이 구문적으로 유효한지 확인하는 가장 빠른 방법입니다. 편집 및 빠른 확인에는 탁월하지만, 자동화된 파이프라인 실행에는 덜 적합합니다. Swagger Editor는 무료이며 완전히 브라우저에서 실행됩니다.
Spectral
Stoplight의 Spectral은 대부분의 팀이 품질 강제를 위해 선택하는 린터입니다. OpenAPI 및 AsyncAPI용 규칙 세트를 제공하며, 진정한 가치는 사용자 지정 규칙에 있습니다. 모든 작업에 설명이 필요하거나 경로에 후행 슬래시를 금지하는 등 자체 규칙을 YAML 또는 JavaScript로 작성하여 적용할 수 있습니다. 명령줄에서 실행되므로 CI에 자연스럽게 통합됩니다. Spectral 프로젝트는 오픈 소스입니다.
openapi-spec-validator
openapi-spec-validator는 한 가지 작업을 잘 수행하는 데 집중된 Python 도구입니다. 버전 2.0, 3.0, 3.1의 공식 OpenAPI 스키마에 대해 사양을 확인합니다. 스타일에는 어떤 의견도 없습니다. 파일이 구조적으로 올바른지 알려줍니다. 라이브러리 또는 CLI로서 Python 기반 빌드 단계 및 pre-commit 훅에 깔끔하게 통합됩니다. 엄격한 합격/불합격 정확성 게이트를 원할 때, 이것은 깔끔한 선택입니다.
Apidog
Apidog는 통합 디자인 워크플로의 일부로 사양을 검증합니다. OpenAPI 정의를 구축하거나 가져올 때, 편집기에서 구조적 문제를 표시합니다. Apidog의 더 독특한 기능은 런타임 검증입니다. 실시간 API 응답을 사양에 선언된 스키마와 비교하여, 구현이 더 이상 계약과 일치하지 않는 드리프트를 잡아냅니다. 이는 유효한 문서와 올바른 API 사이의 간극을 좁힙니다. 하나의 도구에서 사양을 설계하고 검증하려면 Apidog를 다운로드하세요.
Redocly CLI
Redocly CLI는 린팅, 유효성 검사, 문서 생성을 묶어서 제공합니다. OpenAPI 스키마에 대해 유효성을 검사하고, 구성 가능한 규칙 세트를 제공하며, 여러 파일로 된 사양을 하나의 번들로 해결할 수 있습니다. 이미 Redoc으로 문서를 렌더링하는 팀은 추가적인 종속성 없이 동일한 도구 체인에서 유효성 검사를 받을 수 있습니다.
Vacuum
Vacuum은 Go로 작성된 빠른 OpenAPI 린터입니다. 일부 JavaScript 기반 린터가 느려지는 매우 큰 사양에서 속도가 강점입니다. Spectral 스타일 규칙과 호환되므로, 팀은 최소한의 재작업으로 전환할 수 있습니다. 방대한 API 표면을 가진 모노레포의 경우 성능 차이가 눈에 띕니다.
비교표
| 도구 | 유형 | 확인 사항 | CI 실행 | 최적 용도 |
|---|---|---|---|---|
| Swagger Editor | 브라우저 편집기 | 구문, 스키마 | 아니오 | 실시간 편집 및 빠른 확인 |
| Spectral | CLI 린터 | 스타일, 사용자 지정 규칙 | 예 | 디자인 컨벤션 강제 |
| openapi-spec-validator | CLI / Python 라이브러리 | 스키마 정확성 | 예 | 엄격한 합격/불합격 게이트 |
| Apidog | 통합 플랫폼 | 스키마 + 런타임 드리프트 | 예 | 설계 및 응답 검증 |
| Redocly CLI | CLI | 스키마, 스타일, 번들링 | 예 | 문서 및 유효성 검사를 함께 |
| Vacuum | CLI 린터 | 스타일, Spectral 규칙 | 예 | 매우 큰 사양, 속도 |
유효성 검사 워크플로를 구축하는 방법
하나의 도구만 선택하는 것이 아닙니다. 여러 도구를 계층적으로 사용합니다.
편집하는 곳에서 시작하세요. 사양을 작성하는 동안, 입력하는 즉시 오류가 표시되도록 Swagger Editor 또는 통합 플랫폼을 사용하세요. 이렇게 하면 명백한 실수를 즉시 잡아낼 수 있으며, 나중에 잡는 것보다 훨씬 저렴합니다.
CI에 정확성 게이트를 추가하세요. 사양을 건드리는 모든 풀 리퀘스트에 대해 openapi-spec-validator 또는 이에 상응하는 CLI를 실행하세요. 파일이 OpenAPI 스키마에 대해 유효성 검사를 통과하지 못하면 빌드가 실패합니다. 이는 협상 불가능하고 이진적(명확한 합격/불합격)입니다.
그 옆에 품질 게이트를 추가하세요. 팀이 동의하는 규칙 세트를 사용하여 Spectral을 실행하거나, 큰 사양의 경우 Vacuum을 실행하세요. 내장된 OpenAPI 규칙으로 시작한 다음, 자체 컨벤션을 위한 사용자 지정 규칙을 추가하세요. API와 함께 발전할 수 있도록 규칙 세트를 버전 관리하세요. 이는 CI/CD에서 테스트를 자동화하여 신뢰성을 높이는 것과 동일한 원칙입니다. 즉, 누군가가 기억할 때가 아니라 매번 검사가 실행됩니다.
마지막으로, 실행 중인 API를 사양에 대해 검증하세요. 사양은 완벽할 수 있지만 구현은 사양에서 벗어났을 수 있습니다. Apidog를 통하거나 스위트 내의 계약 테스트를 통하는 런타임 검증은 API가 여전히 계약과 일치하는지 확인합니다. 테스트 측면에서 유용한 API 어설션 작성은 문서화된 스키마에 대해 응답을 확인하는 방법을 다룹니다.
흔한 실수: 한 번만 검증하기
많은 팀은 사양을 처음 작성할 때 한 번 검증하고, 그 후에는 다시 검증하지 않습니다. 그러면 사양은 거기서부터 썩어갑니다. 개발자가 코드에 엔드포인트를 추가하고 사양을 잊어버립니다. 누군가 응답 형태를 변경합니다. 6개월 후, 사양은 더 이상 존재하지 않는 API를 설명하고 있으며, 생성된 SDK와 문서는 조용히 틀리게 됩니다.
검증은 지속적이어야 합니다. CI에 연결하여 사양에 대한 모든 변경 사항이 확인되고, API에 대한 모든 변경 사항이 사양에 대해 확인되도록 하세요. 사양 실패를 단위 테스트 실패와 동일하게 처리하세요. 빌드가 통과되지 않아야 합니다. 이 원칙은 일반적인 자동화된 테스트 뒤에 있는 것과 동일합니다. 즉, 아무도 실행하기로 결정하지 않아도 실행될 때만 검사가 가치가 있습니다.
올바른 OpenAPI 버전에 대해 검증하는 것도 도움이 됩니다. 3.1 릴리스는 OpenAPI를 JSON 스키마와 정렬했으며, 이로 인해 일부 스키마 구성 요소의 동작이 변경되었습니다. 도구가 3.0을 가정하지만 사양이 3.1을 선언하는 경우, 오해의 소지가 있는 결과를 얻을 수 있습니다. 공식 OpenAPI 사양은 버전 차이점을 문서화하며, 대부분의 검증기는 버전을 명시적으로 고정할 수 있도록 합니다.
검증기가 잡아내지만 당신이 놓칠 수 있는 것들
"사양이 잘못되었다"는 너무 모호하여 조치를 취하기 어렵기 때문에, 검증이 드러내는 문제의 종류에 대해 구체적으로 아는 것이 중요합니다.
구조적 오류는 가장 쉽게 상상할 수 있습니다. 존재하지 않는 스키마를 가리키는 $ref. OpenAPI에서 필수적인 description이 없는 응답 객체. URL 템플릿에 선언되었지만 parameters 목록에 정의되지 않은 경로 매개변수. 예제는 문자열을 보여주지만 스키마는 type: integer라고 말하는 경우. 정확성 검증기는 이들 각각을 플래그하며, 그렇지 않으면 코드 생성기를 깨뜨리거나 손상된 SDK를 생성할 수 있습니다.
품질 문제는 더 미묘하고 흔합니다. operationId가 없는 작업은 생성된 클라이언트 메서드 이름을 보기 흉하거나 불안정하게 만듭니다. 일부 경로가 snake_case를 사용하고 다른 경로가 camelCase를 사용하는 일관성 없는 경로 대소문자. 200 응답은 문서화했지만 400 또는 401 응답은 전혀 문서화하지 않아 소비자가 오류가 어떻게 생겼는지 알 수 없는 엔드포인트. API가 실제로 요청 본문을 필요로 하는데 선택 사항으로 표시된 경우. 이들 중 어느 것도 파서를 깨뜨리지는 않지만, 모두 API를 사용하기 어렵게 만들며, 린터가 이러한 문제를 방지합니다. 실제 동작과의 연결은 사양 자체는 깨끗해진 후 API 계약 테스트가 검증하는 것입니다.
설계 우선 워크플로에 유효성 검사 통합하기
많은 팀이 이제 코드를 작성하기 전에 API를 설계하고, OpenAPI 사양을 먼저 생성한 다음, 이를 통해 서버 스텁, 목(mock), 문서를 생성합니다. 이러한 모델에서는 유효성 검사가 훨씬 더 중요합니다. 왜냐하면 사양은 기존 API의 문서가 아니라, 다른 모든 것이 구축되는 진실의 원천이기 때문입니다. 사양의 결함은 생성된 서버의 결함이 됩니다.
설계 우선 흐름에서는 설계 시점에 유효성 검사를 수행하세요. 편집기 수준 검사는 사양이 형태를 갖출 때, 어떤 코드 생성도 실행되기 전에 실수를 잡아냅니다. 그런 다음 CI 게이트는 아무것도 퇴보하지 않았음을 확인합니다. 사양이 목 서버를 구동하기 때문에, 깨끗한 사양은 목이 올바르게 작동한다는 것을 의미하며, 이는 프런트엔드 및 클라이언트 팀이 신뢰할 수 있는 대리자를 기반으로 개발할 수 있게 합니다. 사양이 목킹에 어떻게 활용되는지 보려면 테스트를 위한 API 목킹에 대한 저희 가이드를 참조하세요. 이러한 규율은 그 자체로 가치가 있습니다. 사양을 유효하게 유지하는 데 들이는 매 시간은 나중에 불일치하는 클라이언트를 디버깅하는 데 드는 여러 시간을 절약해 줍니다.
자주 묻는 질문
OpenAPI 검증기와 린터의 차이점은 무엇인가요?
검증기는 사양이 OpenAPI 스키마에 대해 구조적으로 올바른지 확인하여 합격/불합격 여부를 알려줍니다. 린터는 모든 작업에 설명이 있는지, 경로 이름이 일관적인지 등 품질과 스타일을 확인합니다. 많은 도구가 이 두 가지를 모두 수행하지만, 서로 다른 질문에 답하며, 강력한 워크플로는 이 둘을 모두 사용합니다.
OpenAPI 사양을 무료로 검증할 수 있나요?
네. Swagger Editor, Spectral, openapi-spec-validator, Redocly CLI, Vacuum은 모두 무료 오픈 소스입니다. Apidog는 무료 티어에서 사양을 검증하고 런타임 검사를 추가합니다. 비용 문제로 유효성 검사를 건너뛸 이유가 없습니다.
OpenAPI 3.0과 3.1을 다르게 검증해야 하나요?
동일한 도구로 검증하지만, 버전을 고정해야 합니다. OpenAPI 3.1은 JSON 스키마와 정렬되어 일부 스키마 동작이 변경되었으므로, 3.0을 예상하는 검증기는 3.1 사양에서 잘못된 오류를 보고할 수 있습니다. 사용하는 도구가 사양에서 선언된 버전을 지원하는지 확인하세요.
사양 유효성 검사는 어디에서 실행되어야 하나요?
두 곳에서 실행되어야 합니다. 사양을 작성하는 동안 편집기에서 실시간으로 실행하여 실수가 즉시 드러나도록 하고, 모든 풀 리퀘스트에서 CI에서 실행하여 손상되거나 품질이 낮은 사양이 병합되지 않도록 합니다. 편집기 전용 유효성 검사는 건너뛰기 쉽지만, CI 유효성 검사는 그렇지 않습니다.
내 API가 사양과 일치하는지 어떻게 확인할 수 있나요?
사양 유효성 검사는 문서가 올바르다는 것만 확인하며, 구현이 문서와 일치하는지는 확인하지 않습니다. 드리프트를 잡아내려면, 실시간 API 응답을 사양의 스키마와 비교하는 계약 테스트 또는 런타임 유효성 검사를 실행하세요. Apidog는 이를 직접 수행하며, 계약 테스트 프레임워크는 테스트 스위트에서 이를 수행합니다.