OpenAPI Diff

이 비교 도구가 검사하는 것 — 그리고 "파괴적"의 진짜 의미

변경이 파괴적인 경우는, 이전 명세에 맞게 올바르게 작성된 클라이언트가 자신의 코드를 한 줄도 바꾸지 않고 새 명세에서 실패할 수 있을 때입니다. 이 페이지의 모든 판정은 이 정의를 따릅니다. 경로나 작업을 제거하는 것은 파괴적입니다. 기존 호출이 갈 곳이 없어지기 때문입니다. 응답 상태 — 특히 2xx — 를 제거하는 것은 파괴적입니다. 클라이언트의 오류 처리가 기존 상태 집합을 전제로 작성됐기 때문입니다. 필수 매개변수나 필수 요청 속성을 추가하는 것은 파괴적입니다. 어제까지 유효하던 요청이 갑자기 거부되기 때문입니다. 필드의 타입이나 형식을 바꾸는 것은 파괴적입니다. 파서, 검증기, 생성된 SDK가 모두 선언된 타입을 전제로 하기 때문입니다. 열거값을 제거하는 것은 파괴적입니다. 클라이언트가 그 값을 여전히 보낼 수도 있고, 더 이상 해석할 수 없는 데이터를 저장하고 있을 수도 있기 때문입니다. 그 외의 모든 것 — 새 엔드포인트, 선택적 매개변수, 새 응답 필드, 새 열거값, 새 상태 코드 — 은 비파괴적으로 보고됩니다. 기존 클라이언트는 계속 동작합니다. 새 기능을 아직 쓰지 못하더라도 말입니다.

비교는 텍스트가 아니라 구조로 이뤄집니다. 두 문서는 비교 전에 같은 모델로 정규화됩니다. 각 경로와 작업, 이름과 위치로 색인된 매개변수, 요청 본문과 각 응답은 스키마 서명으로 축소됩니다. 이는 타입, 형식, 속성 이름, 필수 목록, 열거값으로 재귀적으로 구축되는 결정적 요약이며, 로컬 $ref 참조는 해석됩니다. 그래서 키 순서를 바꾸거나 공백을 다시 포맷하거나 모든 설명을 다시 써도 diff는 비어 있습니다. 그런 것들은 계약을 바꾸지 않기 때문입니다. 그리고 참조되는 스키마 세 단계 깊이 묻힌 변경도 찾아냅니다. 서명은 참조의 이름을 비교하는 것이 아니라 참조를 펼치기 때문입니다.

생태계가 두 형식을 모두 게시하므로 입력 형식은 두 가지를 받습니다. 먼저 JSON으로 시도하고, 실패하면 YAML로 파싱합니다. 손으로 쓴 OpenAPI 문서 대부분이 YAML을 사용합니다. Swagger 2.0 문서도 동작하며, in: body 매개변수와 응답별 스키마를 포함합니다. 의도적으로 실시간 가져오기도, 업로드도 없습니다. HAR 캡처와 똑같이 문서를 붙여 넣거나 파일을 놓으세요. 비교는 키를 누를 때마다가 아니라 버튼을 누를 때 실행되므로, 붙여 넣은 두 개의 큰 명세도 반응성을 유지합니다.

결과를 장식이 아니라 릴리스 게이트로 사용하세요. 리뷰에서 파괴적 목록이 곧 안건입니다. 각 항목에는 수정, 버전 올림, 사용 중단 기간, 또는 "파괴는 의도됐으며 공지됐다"는 서면 결정 중 하나가 필요합니다. 비파괴적 목록은 변경 로그의 초안입니다. diff를 JSON으로 내보내면 그 결정을 릴리스 옆에 보관할 수 있고, 복사 가능한 요약은 풀 리퀘스트에 바로 들어갑니다. 페이로드가 조용히 바뀌면 모든 구독자가 한 번에 깨지는 webhook 계약 변경에 적용할 것과 같은 규율입니다.

정직한 한계를 분명히 말합니다. 이 비교 도구는 선언된 계약을 비교합니다. 명세가 선언하지 않은 동작은 볼 수 없습니다. 타입은 그대로인데 의미가 바뀐 필드, 새 비즈니스 규칙, 더 엄격한 속도 제한, 클라이언트가 (현명하지 못하게) 파싱하던 오류 메시지 같은 것들입니다. 로컬 참조를 따라가며 제한된 깊이까지 스키마를 비교하므로, 병적으로 깊게 중첩되거나 서로 재귀하는 스키마는 무한히 펼쳐지지 않고 요약됩니다. 그리고 파괴적 변경이 0건인 diff는 업그레이드가 안전하다는 약속이 아닙니다. 문서화된 계약이 유지됐다는 증거이며, 바로 그것이 배포 전에 가질 가치가 있는 증거입니다.