Name: openapi-changes - The world's sexiest OpenAPI diffing and breaking change detector tool.
SKU: -

소개

openapi-changes는 OpenAPI 사양 간 변경 사항을 감지하고 분석하는 도구입니다. pb33f에서 개발했으며, 두 개의 OpenAPI 파일 간 차이를 비교하거나 Git 히스토리, GitHub-hosted 파일 URL 등을 통해 시간에 따른 변화를 추적할 수 있습니다. 터미널 UI, JSON, Markdown, HTML 보고서 등 다양한 출력 형식을 지원하며, 완전 오프라인 환경에서도 동작합니다.

상세정보

변경 사항 감지 및 비교

두 개의 OpenAPI 사양 파일 간 모든 변경 사항을 경로, 메서드, 스키마 수준까지 세부적으로 분석하여 추가, 수정, 삭제 항목을 식별합니다. Git 저장소 내 특정 브랜치, 태그, 커밋 간 비교도 지원하며, HEAD~N 형태의 상대 참조를 사용할 수 있습니다.

다양한 출력 형식 지원

명령어에 따라 다음과 같은 형식으로 결과를 출력할 수 있습니다:

summary: 터미널에 간결한 변경 요약 출력
console: 인터랙티브 터미널 UI 실행 (다크, 라이트, 레트로 테마 지원)
report: 기계가 읽을 수 있는 JSON 형식 보고서 생성
markdown-report: 공유 가능한 Markdown 형식 보고서
html-report: 타임라인, 그래프, diff 뷰가 포함된 완전한 오프라인 HTML 보고서

Git 기반 비교 기능

작업 디렉터리를 Git 저장소로 사용할 때, 브랜치명:파일경로 형태의 구문을 통해 체크아웃 없이 특정 revision의 파일을 직접 비교할 수 있습니다. 예를 들어 main:openapi.yaml feature-branch:openapi.yaml 형태의 입력이 가능하며, 태그, HEAD~1, 커밋 SHA 등 모든 Git 참조를 지원합니다.

사용자 정의 브레이킹 변경 규칙

changes-rules.yaml 파일을 통해 브레이킹 변경으로 간주할 조건을 사용자 정의할 수 있습니다. 기본적으로 ./changes-rules.yaml 또는 ~/.config/changes-rules.yaml 경로에서 자동 탐색하며, 경로 아이템, 스키마, 파라미터 등의 요소에 대해 added, modified, removed 규칙을 개별적으로 설정할 수 있습니다.

다운로드 및 설치 방법

다음과 같은 방법으로 openapi-changes를 설치할 수 있습니다:

Homebrew (macOS/Linux): brew install pb33f/taps/openapi-changes
npm (전역 설치): npm i -g @pb33f/openapi-changes
Yarn: yarn global add @pb33f/openapi-changes
cURL을 통한 설치 스크립트: curl -fsSL https://pb33f.io/openapi-changes/install.sh | sh
Docker: docker pull pb33f/openapi-changes 후 작업 디렉터리를 마운트하여 실행

Docker 사용 시, 현재 디렉터리를 /work 경로에 마운트하면 로컬 Git 히스토리 명령을 안전하게 사용할 수 있습니다. 예를 들어 docker run --rm -v $PWD:/work:rw pb33f/openapi-changes summary . sample-specs/petstorev3.json 형태의 명령을 실행할 수 있습니다.

기본 사용법

설치 후 버전 확인은 openapi-changes version 명령으로 수행할 수 있습니다. 주요 사용 예시는 다음과 같습니다:

두 로컬 파일 비교: openapi-changes summary old.yaml new.yaml
Git 히스토리 기반 비교: openapi-changes summary HEAD~1:openapi.yaml ./openapi.yaml
인터랙티브 콘솔 실행: openapi-changes console . path/to/openapi.yaml (Docker 사용 시 -it 플래그 추가)
HTML 보고서 생성: openapi-changes html-report main:api/openapi.yaml feature-branch:api/openapi.yaml
JSON 보고서 출력: openapi-changes report old.yaml new.yaml > changes.json

도움말은 openapi-changes --help 또는 특정 서브커맨드에 대해 openapi-changes --help로 확인할 수 있습니다.

이런 경우에 유용합니다

API 개발 팀이 릴리스 전후 사양 변경을 검토해야 할 때, openapi-changes를 통해 의도치 않은 브레이킹 변경 사항을 사전에 탐지할 수 있습니다. CI/CD 파이프라인에 통합하여 풀 리퀘스트 시 자동으로 변경 보고서를 생성하면, 리뷰어가 API 변경의 영향을 빠르게 이해하고 의사결정할 수 있도록 지원합니다. 또한 오프라인 HTML 보고서는 네트워크 제한이 있는 환경에서도 이해관계자와 변경 사항을 공유하는 데 유용합니다.

지원 환경·시스템 요구사항

소스 코드로부터 직접 빌드하는 경우 Go 1.25.7 이상이 필요합니다. 배포된 바이너리 또는 패키지(Homebrew, npm, Docker 등)를 사용하는 경우 별도의 런타임 의존성은 필요하지 않으며, Windows를 포함한 주요 플랫폼에서 실행 가능합니다. Docker 이미지는 linux/amd64 및 linux/arm64 아키텍처를 지원하며, 내부적으로 Git을 신뢰하도록 설정되어 마운트된 저장소에서 safe.directory 설정 없이도 히스토리 명령을 사용할 수 있습니다.

시스템 요구사항

별도의 시스템 요구사항이 등록되지 않았습니다.

openapi-changes – The world’s sexiest OpenAPI diffing and breaking change detector tool.

소개