OpenAPI 비교 및 호환성 깨짐 검사기

OpenAPI Diff는 기준 API 명세와 후보 API 명세를 텍스트가 아닌 의미로 비교합니다. 메서드와 경로로 작업을 매칭하고(따라서 /users/{id}와 /users/{userId}는 같은 엔드포인트입니다), 내부 $ref 참조를 해석하며, 각 계약 변경을 해당 작업, 위치, 변경 전후 값, 그리고 클라이언트에 중요한 이유와 함께 보고합니다. JSON 또는 YAML 형식의 Swagger 2.0, OpenAPI 3.0, OpenAPI 3.1을 지원하며, Swagger 2.0은 먼저 OpenAPI 3 구조로 정규화됩니다.

1. 1.기준 명세(클라이언트가 현재 사용하는 버전)를 붙여넣거나 업로드하거나 가져옵니다.
2. 2.후보 명세(제안된 버전)를 추가합니다.
3. 3.비교를 선택합니다.
4. 4.호환 불가, 경고, 호환 탭을 확인하고 메서드나 영역별로 필터링합니다.
5. 5.변경 사항을 선택해 변경 전후 값과 중요한 이유를 확인합니다.
6. 6.풀 리퀘스트용으로 호환 불가 변경을 복사하거나, CI용 Markdown 또는 JSON 보고서를 다운로드합니다.

요청과 응답은 서로 반대 방향으로 판단합니다. 요청 쪽(클라이언트가 보내는 것)에서는 허용 범위를 좁히는 모든 변경이 호환 불가입니다. 새로운 필수 파라미터나 속성, 제거된 enum 값, 변경된 타입이나 포맷, 낮아진 최댓값이나 높아진 최솟값, 새 패턴, 제거된 콘텐츠 타입이 해당합니다. 응답 쪽(클라이언트가 받는 것)에서는 클라이언트가 읽는 내용을 제거하거나 넓히는 모든 변경이 호환 불가 또는 경고입니다. 제거된 속성이나 성공 상태, 변경된 타입, 새 enum 값, 필수에서 선택으로 바뀐 속성이 해당합니다. 제거된 엔드포인트, 새로 추가된 인증, 변경된 보안 스킴, 추가된 OAuth 스코프는 호환 불가입니다. 설명, 요약, 제목, 예시 수정은 문서 변경이며 켜기 전에는 숨겨집니다.

비교는 내장 규칙 엔진을 사용해 브라우저에서 실행되며, 명세는 업로드되지 않습니다. URL 가져오기는 쿠키 없이 브라우저에서 직접 파일을 가져오므로, 교차 출처 요청을 차단하는 서버의 명세는 업로드하거나 붙여넣어야 합니다. 각 명세는 최대 5 MB까지 가능합니다. 외부 $ref 파일은 보고되지만 가져오지 않습니다. 서버, 콜백, 웹훅, 링크, 벤더 확장은 비교하지 않으며, 규칙은 클라이언트에 미칠 가능성이 높은 영향을 설명할 뿐 보장하지 않습니다. 엄격한 서버와 관대한 서버는 다르게 동작할 수 있습니다.