같은 팀의 두 엔지니어가 같은 주에 두 개의 엔드포인트를 출시했습니다. 하나는 created_at을 반환하고, 다른 하나는 createdAt을 반환합니다. 하나는 ?page=로 페이지를 매기고, 다른 하나는 ?offset=으로 페이지를 매깁니다. 어느 것도 그 자체로는 잘못되지 않았습니다. 하지만 함께 있으면 API가 마치 낯선 사람들에 의해 조립된 것처럼 느껴지고, 이를 사용하는 모든 클라이언트는 대가를 치러야 합니다. OpenAPI 파일은 잘 유효성 검사를 통과합니다. 구문 분석되고, Swagger UI에 렌더링되며, SDK를 생성합니다. 단지 일관성이 없을 뿐이며, 일반적인 유효성 검사기는 이에 대해 아무 말도 하지 않습니다.
바로 이러한 간극을 린터가 채워줍니다. 유효성 검사기는 "이 사양이 유효한 OpenAPI입니까?"라고 묻고, 린터는 "이 사양이 우리가 합의한 규칙을 따릅니까?"라고 묻습니다. 후자의 질문에 대한 가장 인기 있는 오픈소스 도구는 JSON 및 YAML 문서용 Stoplight의 린터인 Spectral입니다. 이 도구는 내장된 OpenAPI 규칙 세트를 제공하며, 사용자 고유의 규칙을 작성할 수 있고, 터미널이나 에디터에서 실행할 수 있습니다. API 스타일 가이드를 적용할 수 있는 무료의 스크립트 가능한 방법을 원한다면 Spectral이 가장 먼저 고려해야 할 도구이며, 이 가이드는 Spectral을 올바르게 사용하는 방법을 보여줍니다.
이 글은 또한 장단점을 보여줍니다. Spectral은 사용자가 직접 조립하고 유지 관리하는 규칙 세트입니다. YAML 규칙을 수동으로 작성하지 않고 일관성 검사, 목 서버 및 실행 가능한 테스트를 한 곳에서 얻으려는 팀에게는 Apidog가 그 작업을 디자인 화면 자체에 통합합니다. 먼저 Spectral의 장점을 충분히 설명한 다음, 올인원 방식이 유지 관리 비용을 어떻게 절감하는지 보여드리겠습니다.
Spectral은 실제로 무엇을 하는가
Spectral은 일반적인 린터입니다. 구조화된 문서를 가리키고, 규칙 세트를 제공하면, 문서가 규칙을 위반한 모든 위치를 줄 번호와 심각도와 함께 보고합니다. OpenAPI에만 국한되지 않습니다. 기본적으로 OpenAPI, AsyncAPI, Arazzo를 이해하며, 사용자 정의 규칙을 사용하여 모든 JSON 또는 YAML 파일을 린트할 수 있습니다.
API 작업에서 중요한 이유는 내장된 spectral:oas 규칙 세트 때문입니다. 이 규칙 세트는 operationId를 가져야 하는 작업, 설명 및 연락처를 포함해야 하는 info 객체, 사용되기 전에 정의되어야 하는 태그, 서로 중복되어서는 안 되는 매개변수 등 OpenAPI 컨벤션의 긴 목록을 인코딩합니다. 실제 사양에 대해 실행하면 거의 항상 첫 시도에 경고 목록을 받게 될 것입니다. 이들 중 어느 것도 파서를 깨뜨리지는 않습니다. 하지만 이들 모두 사양을 다루기 어렵게 만듭니다.
이는 구조적 유효성 검사와는 다른 작업입니다. swagger-cli 또는 Redocly와 같은 도구는 문서가 OpenAPI 스키마를 준수하는지 여부에 답합니다. Spectral은 문서가 그 위에 여러분의 사내 스타일을 따르는지 여부에 답합니다. 둘 다 필요하며, 두 가지 검사는 파이프라인에서 깔끔하게 구성됩니다. OpenAPI 사양을 유효성 검사하는 방법 가이드에서 유효성 검사 절반을 다루며, 이 글은 스타일 및 일관성 절반에 대한 것입니다.
Spectral 설치 및 첫 린트 실행
Spectral은 npm 패키지로 제공됩니다. CLI는 @stoplight/spectral-cli입니다. 전역으로 설치하세요:
npm install -g @stoplight/spectral-cli
Node.js는 유일한 시스템 종속성이므로, Node가 이미 설치된 모든 머신이나 CI 이미지에서 실행할 수 있습니다. 전역으로 설치하고 싶지 않다면, npx @stoplight/spectral-cli ...를 사용하여 임시 빌드 러너에서 작동합니다.
Spectral은 무엇을 확인할지 알기 위해 규칙 세트가 필요합니다. 관례적으로 작업 디렉토리에 .spectral.yaml이라는 파일이 있습니다. 가장 작은 유용한 파일은 내장된 OpenAPI 규칙을 확장합니다:
# .spectral.yaml
extends: ["spectral:oas"]
이제 사양을 린트합니다. 현재 디렉토리에 .spectral.yaml 파일이 있으면 Spectral이 자동으로 이를 인식합니다:
spectral lint openapi.yaml
또는 규칙 세트를 명시적으로 지정합니다:
spectral lint openapi.yaml --ruleset .spectral.yaml
출력은 의도적으로 가독성이 좋습니다. 각 발견 항목은 줄과 열, 심각도, 실행된 규칙 및 사람이 읽을 수 있는 메시지를 보여줍니다:
openapi.yaml
3:6 warning info-contact Info object should contain `contact` object.
5:10 error info-description OpenAPI object info `description` must be present.
✖ 2 problems (1 error, 1 warning, 0 infos, 0 hints)
기존 사양에 대한 첫 실행은 대부분의 팀이 얼마나 많은 불일치가 스며들어왔는지 깨닫는 순간입니다. 규칙이 전혀 적용되지 않았기 때문에 아무도 따르지 않았던 것입니다.
사용자 고유의 규칙 작성
내장된 규칙 세트는 시작점이지 종착역이 아닙니다. Spectral의 진정한 가치는 팀의 컨벤션을 변경 사항마다 기계가 검사하는 규칙으로 인코딩하는 데 있습니다. 규칙은 네 가지 구성 요소를 가집니다: 무엇을 볼 것인지(given, JSONPath 표현식), 무엇을 확인할 것인지(then, 함수), 얼마나 엄격하게 적용할 것인지(severity), 그리고 실패 시 무엇을 말할 것인지(message).
다음은 일반적인 사내 컨벤션인 케밥 케이스 경로를 강제하는 규칙입니다:
# .spectral.yaml
extends: ["spectral:oas"]
rules:
paths-kebab-case:
description: Paths should be kebab-case.
message: "{{property}} should be kebab-case (lower-case, hyphen-separated)"
severity: warn
given: $.paths[*]~
then:
function: pattern
functionOptions:
match: "^(\\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"
given은 모든 경로 키를 선택합니다. then은 정규 표현식에 대해 내장 pattern 함수를 실행합니다. 패턴에 실패하는 모든 항목은 사용자 메시지와 함께 경고로 보고됩니다. UUID 대신 정수 ID를 금지하거나, 모든 POST에 오류 응답을 요구하거나, 서버 URL에서 버전 번호를 금지하거나, 모든 작업에 설명이 포함되도록 요구할 수 있습니다. Spectral은 여러 핵심 함수(truthy, pattern, schema, length, enumeration 등)를 제공하므로 대부분의 컨벤션은 코드가 전혀 필요 없습니다.
함수 옵션이 표현할 수 없는 로직이 규칙에 필요한 경우, Spectral은 JavaScript 또는 TypeScript로 규칙을 작성하고 사용자 정의 함수를 가져올 수 있도록 합니다. 이 부분이 도구가 강력해지는 지점이며, 유지 관리가 시작되는 지점이기도 합니다. 더 깊이 들어가고 싶다면, TypeScript로 사용자 정의 Spectral 규칙을 구축하는 방법에 대한 전체 안내서를 참고하십시오.
심각도, 그리고 빌드 실패 설정
모든 Spectral 규칙에는 심각도(error, warn, info, hint)가 있습니다. 기본적으로 CLI는 error를 발견했을 때만 0이 아닌 코드로 종료됩니다. 경고는 출력되지만 실행을 실패시키지는 않습니다. 이는 레거시 사양을 정리하는 동안 수많은 경고가 모든 병합을 막는 것을 원하지 않을 때 좋습니다.
사양이 정리되면 게이트를 강화하십시오. --fail-severity 플래그는 임계값을 제어합니다:
spectral lint openapi.yaml --fail-severity=warn
이제 경고도 종료 코드 1을 반환하며, 이는 CI 단계에서 실패로 표시하기 위해 읽는 값입니다. 이것이 린터를 실제 품질 게이트로 바꾸는 메커니즘입니다: 사양이 스타일 가이드에서 벗어나는 순간 파이프라인이 병합을 차단합니다. 규칙 세트에서 개별 규칙 심각도를 재정의하여, 중요한 규칙을 warn에서 error로 올리거나, 팀에 맞지 않는 규칙을 off로 설정하여 비활성화할 수도 있습니다.
CI에서 Spectral 실행
누군가가 기억할 때만 실행되는 린터는 게이트가 아닙니다. 요점은 모든 푸시에 대해, 깨끗한 머신에서, 모든 사람에게 동일한 규칙 세트로 실행하는 것입니다. Spectral은 이를 간단하게 만듭니다. 다음은 사양을 건드리는 모든 풀 리퀘스트에 대해 린트하는 GitHub Actions 작업입니다:
name: Lint OpenAPI
on:
pull_request:
paths:
- "openapi.yaml"
jobs:
spectral:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "20"
- run: npm install -g @stoplight/spectral-cli
- run: spectral lint openapi.yaml --fail-severity=warn
더 풍부한 보고를 위해 Spectral은 JUnit XML을 출력할 수 있으며, 대부분의 CI 대시보드는 이를 통과/실패 트리로 구문 분석합니다:
spectral lint openapi.yaml -f junit -o results.xml
해당 아티팩트를 대시보드에 연결하면 모든 기여자가 원시 로그를 읽지 않고도 어떤 규칙이 어디에서 실패했는지 확인할 수 있습니다. 구조적 검사, 린팅 및 파괴적 변경 감지를 함께 계층화하는 더 넓은 그림을 원한다면, CI 내 OpenAPI 패턴은 단일 도구를 넘어 일반화됩니다. 사양을 코드로 취급하는 것이 이 모든 것을 성공시키는 사고방식입니다.
Spectral이 많은 것을 요구하는 부분
Spectral은 본연의 역할을 잘 수행합니다. 솔직히 말해서, 그것은 한 가지 일만 하며, 나머지 사양 수명 주기는 사용자가 직접 연결해야 하는 문제입니다. 팀이 데모를 넘어 이를 채택하면 몇 가지 현실적인 문제점이 드러납니다.
규칙 세트는 사용자의 소유입니다. 내장된 spectral:oas 규칙은 일반적입니다. 실제 스타일 가이드는 사용자가 작성하고, 검토하고, 버전을 지정하며, 컨벤션이 발전함에 따라 최신 상태로 유지하는 사용자 정의 규칙에 있습니다. 이 규칙 세트는 자체 유지 관리 부담이 있는 작은 코드베이스가 되며, JSONPath와 사용자 정의 함수는 팀의 모든 구성원이 가지고 있는 기술은 아닙니다.
Spectral은 API가 아니라 문서를 린트합니다. Spectral은 파일을 읽습니다. 실행 중인 서비스가 사양에서 약속한 것을 실제로 반환하는지 여부를 알려줄 수 없습니다. 사양은 모든 린트 규칙을 통과할 수 있지만, 구현이 몇 달 전에 벗어난 엔드포인트를 설명할 수도 있습니다. 이 간극을 메우는 것은 실제 요청을 보내고 응답을 단언하는 것을 의미하며, 이는 완전히 다른 도구입니다.
이는 더 긴 체인의 한 조각일 뿐입니다. 린팅 후에도 프론트엔드 팀을 위한 목(mock) 서버, 문서 사이트 및 자동화된 테스트 스위트가 여전히 필요합니다. 각각은 사양과 동기화하기 위해 설치, 구성 및 유지해야 하는 별도의 도구입니다. 린터는 이들 중 어느 것도 알지 못하므로, 사양은 모든 단계에서 다시 구문 분석되고 다시 해석됩니다.
이 모든 것이 Spectral을 폄하하는 것은 아닙니다. Spectral은 집중된 린터이며 그 범위에 대해 솔직합니다. 그러나 "집중적"이라는 것은 통합 작업이 사용자에게 달려 있음을 의미합니다.
더 쉬운 방법: 디자인 화면에 내장된 일관성
여기 또 다른 방법이 있습니다. 일관성을 사양 작성 후 추가되는 린트 단계로 취급하는 대신, Apidog는 이를 사양 작성의 일부로 취급합니다.
Apidog는 올인원 API 플랫폼입니다: 하나의 워크스페이스에서 스키마를 설계하고, 요청을 디버그하고, 테스트 시나리오를 구축하고, 엔드포인트를 모의하고, 문서를 게시합니다. 디자인이 도구 내부에서 이루어지므로, 입력하는 순간 일관성 검사가 수행됩니다. 시각적 디자이너는 구문 오류를 밑줄 긋는 컴파일러처럼 구조적 문제가 나타나는 즉시 이를 드러내므로, 커밋에 도달하기 전에 문제를 해결할 수 있습니다. 별도의 린터를 사후에 실행하는 것이 아니라, 에디터 자체가 린터입니다.
더 큰 차이점은 모든 다운스트림 작업입니다. 설계한 동일한 계약이 다시 구문 분석하거나 동기화를 위해 두 번째 도구를 사용할 필요 없이 목 서버, 대화형 문서 및 테스트 시나리오가 됩니다. 파이프라인에서 이러한 검사를 원할 때, Apidog CLI는 터미널에서 헤드리스 방식으로 테스트 시나리오를 실행하고 실패 시 0이 아닌 값으로 종료됩니다. 이는 린터에서 원했던 게이트 동작과 정확히 일치하지만, 파일을 읽는 대신 실행 중인 API를 계약과 비교하여 테스트합니다. 하나의 npm 명령으로 설치하고 시나리오를 가리키면 됩니다:
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -r cli
이는 Spectral이 남겨둔 간극을 채워줍니다. Spectral은 문서가 스타일을 따르는지 확인합니다. Apidog CLI는 구현이 여전히 문서와 일치하는지 확인합니다. 전체 플래그 참조는 apidog run --help를 실행하거나 전체 CLI 가이드를 참조하십시오.
따라서 장단점은 분명하며 명확하게 언급할 가치가 있습니다. Spectral은 사용자가 조립하고 유지 관리하는 무료의 스크립트 가능한 공급업체 중립적인 린터를 제공합니다. Apidog는 하나의 진실된 소스에서 일관성, 목(mocking), 문서 및 실행 가능한 테스트를 제공하며, 연결해야 할 것이 훨씬 적습니다. 기존 도구 체인에서 이식 가능한 린트 단계만 필요하다면 Spectral이 좋은 답입니다. 전체 수명 주기가 자체적인 도구 프로젝트가 되지 않고 유지되기를 원한다면, 통합된 경로가 장기적으로 비용을 절감합니다.
Spectral vs Apidog 한눈에 보기
| 기능 | Spectral | Apidog |
|---|---|---|
| OpenAPI 스타일 린팅 | 예, spectral:oas + 사용자 정의 규칙을 통해 |
예, 디자이너에서 실시간으로 표시됩니다 |
| 사용자 정의 규칙 | 예, YAML 또는 JS/TS, 직접 유지 관리 | 에디터가 강제하는 규칙, 규칙 코드 불필요 |
| 구조적 유효성 검사 | Redocly 또는 유효성 검사기와 함께 | 설계 시 내장 |
| 목(Mock) 서버 | 아니요 | 예 |
| 자동 생성 문서 | 아니요 | 예 |
| 실행 가능한 API 테스트 | 아니요 | 예, Apidog CLI를 통해 |
| CI 게이트 | spectral lint --fail-severity=warn |
apidog run 비제로 종료 |
| 비용 | 무료, 오픈소스 | 무료 티어, 유료 플랜 |
이 표를 점수판이 아닌 의사 결정 보조 도구로 사용하십시오. 올바른 선택은 단일 도구가 수명 주기의 얼마나 많은 부분을 소유하기를 원하는지에 따라 달라집니다.
자주 묻는 질문
Spectral은 무료인가요? 네. Spectral은 Apache 2.0 라이선스 하의 오픈소스이며, Stoplight에서 유지 관리합니다. CLI, 내장 OpenAPI 규칙 세트, 그리고 사용자 정의 규칙 작성 기능 모두 무료로 사용할 수 있습니다.
Spectral이 제 사양이 유효한 OpenAPI인지 유효성 검사하나요? 부분적으로 그렇습니다. 내장 규칙은 많은 구조적 문제를 포착하지만, Spectral은 전용 스키마 유효성 검사기가 아니라 린터입니다. 완전한 구조적 커버리지를 위해 유효성 검사기와 함께 사용하세요. OpenAPI 사양 유효성 검사에 대한 가이드는 그 측면을 다루고 있으며, 최고의 OpenAPI 유효성 검사 도구는 옵션을 비교합니다.
Spectral이 실행 중인 제 API를 테스트할 수 있나요? 아니요. Spectral은 사양 파일만 읽습니다. 라이브 API가 계약과 일치하는지 확인하려면 Apidog CLI와 같이 실제 요청을 보내고 응답을 단언하는 러너가 필요합니다.
Spectral 경고가 CI 빌드를 실패하게 하려면 어떻게 해야 하나요? spectral lint openapi.yaml --fail-severity=warn을 실행하세요. 기본적으로 error 심각도만 빌드를 실패시킵니다. --fail-severity=warn을 사용하면 경고도 0이 아닌 종료 코드를 반환하게 됩니다.
Spectral과 Apidog의 차이점은 무엇인가요? Spectral은 사용자가 구성하고 유지 관리하는 집중적인 오픈소스 린터입니다. Apidog는 디자인, 일관성 검사, 목(mocking), 문서 및 테스트가 함께 존재하는 올인원 플랫폼이므로 조립할 것도, 동기화할 것도 적습니다. 디자인 도구 환경에 대한 관련 비교는 Apidog vs Swagger를 참조하세요.
마무리하며
Spectral은 간단한 유효성 검사기가 무시하는 실제 문제를 해결합니다: 팀이 합의한 컨벤션에 따라 OpenAPI 사양을 일관되게 유지하는 것입니다. @stoplight/spectral-cli을 설치하고, spectral:oas를 확장하고, 몇 가지 사용자 정의 규칙을 추가한 다음, --fail-severity=warn으로 파이프라인을 게이트하세요. 많은 팀에게는 이것으로 충분하며, 비용은 들지 않습니다.
비용은 나중에, 사용자가 유지 관리하는 규칙과 린터 주변에 연결하는 나머지 수명 주기에서 나타납니다. 만약 일관성, 목(mock), 문서 및 실행 가능한 테스트를 하나의 진실된 소스에서 얻고 싶다면, Apidog를 다운로드하여 검사가 이미 표면의 일부인 곳에서 사양을 구축하세요. 어느 쪽이든 목표는 동일합니다: 희망이 아닌 기계에 의해 강제되는, 팀 전체가 신뢰할 수 있는 사양을 만드는 것입니다.