원문 캡처 · github.com
원문 캡처 · github.com

Zof API Contract Check는 지원하는 OpenAPI JSON 계약 두 개를 비교해 병합 전에 호환성을 깨뜨릴 수 있는 변경을 찾는 명령줄 도구다. 비교는 오프라인으로 이뤄지며 Zof 계정이나 소스 업로드가 필요하지 않다.

응답 필드 id가 정수에서 문자열로 바뀌는 경우처럼 호환성 문제를 보고한다. OpenAPI 3.0/3.1 JSON 계약과 문서에 명시된 JSON Schema 하위 집합을 지원한다. YAML, allOf·oneOf·anyOf, 외부 참조는 지원하지 않으며, 이런 입력은 분석 불완전 오류를 반환한다. 사용 전 지원 범위와 한계를 확인해야 한다.

시연 영상은 공개된 0.1.1 패키지와 합성 예제로 만들었으며, 읽기 쉽도록 재생 속도를 조정했다. 명령과 결과는 아래에 글로도 제시돼 있다. 터미널 녹화를 볼 수 있다.

Node.js 22 또는 24, npm, Python 3.10 이상이 설치된 Linux나 macOS에서 사용할 수 있다. Windows에서는 파일 작업이 안전을 위해 실패하도록 처리된다. 새 프로젝트 디렉터리에서 공개 버전을 설치하고, 의도적으로 호환성을 깨뜨리는 예제를 실행하는 방법은 다음과 같다.

bash
npm install --ignore-scripts --save-exact @zof-ai/api-contract-check@0.1.1
npx --no-install zof-api-contract-check baseline.json breaking.json --root node_modules/@zof-ai/api-contract-check/examples --kind openapi --markdown

첫 명령은 의도대로 종료 코드 1을 반환한다. 기준 계약은 id를 정수로, 비교 대상 계약은 문자열로 선언한다. 정수를 기대하는 클라이언트가 있다면 이 변경을 배포하기 전에 검토해야 한다. 도구가 출력하는 결과는 다음과 같다.

text
- **high** type-incompatible: The accepted or returned value type is incompatible. (GET /items/responses/200/schema/properties/id)

전체 보고서에는 분석 한계도 포함된다. 호환되는 예제는 다음 명령으로 비교할 수 있다.

bash
npx --no-install zof-api-contract-check baseline.json compatible.json --root node_modules/@zof-ai/api-contract-check/examples --kind openapi --json

이 명령은 종료 코드 0을 반환하며 지원하는 검사에서 compatible: true라고 보고한다. 어느 명령도 API를 실행하거나 요청을 보내지 않으며, 런타임 호환성을 입증하지 않는다.

패키지에는 컴파일된 JavaScript, TypeScript 선언 파일, 런타임 의존성, 합성 예제가 들어 있다. --ignore-scripts는 설치 생명주기 스크립트를 비활성화하고, --no-install은 이후 명령이 다른 패키지를 내려받지 않도록 한다. 패키지는 npm의 @zof-ai/api-contract-check에서 확인할 수 있다.

자체 계약을 비교하려면 기준 파일과 비교 대상 파일을 지정한 디렉터리 안에 두고 다음과 같이 실행한다.

bash
npx --no-install zof-api-contract-check baseline.json candidate.json --root contracts --kind openapi --markdown

독립형 JSON Schema 파일에는 --kind json-schema를 사용한다. 이 비교는 허용되는 입력을 기준으로 하므로, 비교 대상의 제약이 더 좁아지면 비호환으로 처리한다. 기본 보고서는 Markdown이며, --json을 지정하면 구조화된 결과를 얻는다. 선택 사항인 --policy policy.json은 같은 루트 디렉터리 안에서 정책 파일을 읽으며, 결과를 삭제하지 않고 심각도와 실패 기준을 바꿀 수 있다.

종료 코드는 다음 의미를 갖는다.

  • 0: 지원하는 검사를 마쳤으며 정책상 실패 기준보다 낮다. 검사 통과로 처리한다.
  • 1: 발견 사항이 실패 기준에 도달했다. 계약 변경을 검토해야 한다.
  • 2: 입력이 잘못됐거나 읽을 수 없거나, 지원하지 않거나, 분석이 불완전하다. 입력이나 검사 범위의 공백을 고쳐야 하며 통과로 처리해서는 안 된다.

GitHub Actions에서 풀 리퀘스트 검사를 추가하려면 전체 워크플로 파일을 .github/workflows/api-contract.yml에 복사한 뒤, 두 openapi.json 경로를 저장소 기준 계약 파일 경로로 바꾼다. 이 워크플로는 패키지의 CLI로 풀 리퀘스트의 정확한 기준 커밋과 헤드 커밋을 비교한다. 도구를 별도로 설치하며, 체크아웃한 애플리케이션 코드는 설치하거나 실행하지 않는다.

사전 조건과 경로 설정, 브랜치 보호, 워크플로의 한계는 CI 빠른 시작 안내에서 확인할 수 있다. 별도의 Zof GitHub Action은 일반적인 소스 검사를 수행하며, 이 워크플로는 API Contract Check를 직접 호출한다.

실습 안내는 공개 npm 패키지와 합성 입력을 사용한다. 응답 필드가 정수에서 문자열로 바뀌는 경우, 새로운 필수 쿼리 매개변수 때문에 이를 생략하는 호출자가 영향을 받는 경우, 배포 과정에서 인증 선언이 바뀌는 경우를 다룬다. 각 사례에는 실행 가능한 명령, 실제 발견 사항, 예상 종료 코드, 후속 확인 단계가 담겨 있다. 이는 재현 가능한 학습용 예제이며 고객 사례의 결과가 아니다.

라이브러리로 사용할 때는 다음 API를 제공한다.

javascript
import { compareContracts, readContract, renderMarkdown } from '@zof-ai/api-contract-check';
const baseline = await readContract(process.cwd(), 'baseline.json');
const candidate = await readContract(process.cwd(), 'candidate.json');
const report = compareContracts(baseline, candidate, { failOn: 'high' });
console.log(renderMarkdown(report));

지원 옵션과 발견 사항은 API 참조 문서에 설명돼 있다. GitHub 소스에서 빌드하려면 고정된 소스 설치 및 개발 안내를 따르면 된다. npm 사용자는 저장소를 빌드하지 않고도 위의 빠른 시작 절차를 이용할 수 있다.

이 도구는 원격 측정이나 호스팅 통합을 구현하지 않았다. 독립적으로 작성됐으며 Apache-2.0 라이선스를 따른다. 추가로 보안 안내, 기여 안내, 릴리스 기준을 확인할 수 있다.