01
이전과 새 버전의 방향 고정
기존 클라이언트의 관점에서 판단합니다. 두 입력을 바꾸면 미리보기가 뜨고, 적용 후 한 번 되돌려 입력과 보고서를 복구할 수 있습니다.
API 계약 도구
OpenAPI 스펙 비교배포 전에 변경 영향 확인
이전 명세와 새 명세를 각각 붙여 넣고 수동으로 비교합니다.
OpenAPI 스펙 비교
이전 명세
새 명세
변경 보고서
두 명세는 이 브라우저에서 처리되며 API 요청을 보내지 않습니다.
비교 옵션
범위: 요청 작업, 매개변수, 요청 본문, 응답. 정적 보고서는 실제 호환성을 증명하지 않습니다.
두 명세를 붙여 넣고 비교하세요.
OpenAPI 스펙 비교는 이미 배포된 계약을 바꿀 때 필요합니다. 단순한 줄 단위 diff에서는 제거된 경로와 새 필수 매개변수가 기존 호출을 깨뜨리는지 판단하기 어렵습니다.
이 도구는 OpenAPI Diff 결과를 엔드포인트별로 정리합니다. 확실하지 않은 API 변경 사항은 검토 대상으로 남겨 두어 하위 호환성 검사를 완료했다고 오해하지 않게 합니다.
OpenAPI 스펙 비교를 쓰는 이유
기존 호출을 기준으로 위험 보기
OpenAPI 스펙 비교는 이전 계약에서 새 계약으로 향합니다. 응답 필드 삭제와 새 경로 추가를 따로 표시해 브레이킹 체인지 후보부터 살필 수 있습니다.
제외 범위를 보고서에 남기기
정확히 일치하는 경로를 두 명세에서 함께 제외합니다. 무시한 경로도 보고서에 기록하므로 검토자는 비교 범위를 다시 확인할 수 있습니다.
비교 전에 확인할 세 가지
02
제외 경로는 완전히 일치해야 함
/internal/health처럼 OpenAPI path 키를 한 줄에 하나씩 적습니다. 정규식이나 JSON Pointer가 아니며 변경하면 보고서를 다시 생성해야 합니다.
03
필터와 내보내기를 구분
위험 필터는 화면 목록만 좁힙니다. 복사한 JSON과 다운로드한 Markdown은 최신 전체 결과와 제외된 경로를 포함합니다.
명세에서 추적하는 변경 항목
경로와 메서드
기존 작업이 제거되면 잠재적 파괴 변경으로 분류하고 새 작업은 별도로 보여 줍니다. API 변경 사항을 텍스트 줄보다 쉽게 검토할 수 있습니다.
요청과 응답
새 필수 매개변수, 필수 요청 속성, 제거된 응답과 필드를 확인합니다. 로컬에서 해석 가능한 간단한 스키마 형식과 enum 변화도 표시합니다.
근거가 담긴 보고서
각 항목에 메서드, 경로, 규칙, 변경 전후 값을 담습니다. 결과가 최신일 때만 전체 JSON과 Markdown을 내보낼 수 있습니다.
정적 비교의 적용 범위
- 원격 URL은 가져오지 않음
- 붙여 넣은 JSON 또는 YAML만 처리합니다. 명세 주소를 요청하거나 실제 API를 호출하지 않습니다.
- 경로 제외는 정확한 이름만
- 와일드카드, 정규식, callback 경로는 포함하지 않습니다. 경로 이름이 바뀌면 제거와 추가로 보입니다.
- 해석하지 못한 참조는 중단
- 외부 $ref, 미지원 방언, webhook과 callback이 있으면 완전한 위험 보고서를 내보내지 않습니다.
- 실행 중 호환성을 증명하지 않음
- 서버 동작이나 모든 SDK의 영향을 정적 명세만으로 알 수 없습니다. 배포 전 소비자 테스트를 진행하세요.
OpenAPI 스펙 비교에 관한 질문
OpenAPI 스펙에서 파괴적 변경 사항을 어떻게 감지하나요?
이전과 새 명세를 비교하면 제거된 작업, 필수 입력 추가, 응답 필드 삭제를 잠재적 파괴 변경으로 보여 줍니다. 규칙과 변경 전후 값을 확인하세요.
여기 붙여 넣은 JSON이 어딘가에 저장되거나 업로드되나요?
아니요. OpenAPI 스펙 비교는 브라우저에서 처리하며 입력을 서버에 업로드하거나 저장하지 않습니다. 결과를 남기려면 직접 보고서를 다운로드해야 합니다.
키 재정렬이나 JSON의 pretty-print가 변경으로 표시되나요?
아니요. 구조화된 JSON 또는 YAML을 분석하므로 키 순서나 들여쓰기만 바뀌어도 변경 항목이 생기지 않습니다.
주석이나 끝쉼표가 있는 JSON을 붙여 넣어도 되나요?
JSON의 주석이나 끝쉼표는 허용하지 않습니다. 유효한 JSON 또는 YAML 1.2 한 문서를 사용하고, 오류가 나면 표시된 줄을 수정하세요.
한 번에 두 개보다 많은 JSON 파일을 비교할 수 있나요?
한 번에 이전 문서와 새 문서 두 개를 비교합니다. 세 개 이상의 버전을 연속 비교하거나 히스토리를 저장하는 기능은 제공하지 않습니다.
비교가 도움이 되었나요?