OpenAPI 계약 검사기
API 명세를 편집할 때 경로 변수와 매개변수가 어긋나거나 참조 대상이 사라지면 클라이언트 구현이 막힙니다. 이 도구는 OpenAPI 문서를 로컬에서 파싱하여 핵심 경로·참조·요청·응답 선언을 확인하고 작업별 HTTP 요청 초안을 보여줍니다. 전체 OpenAPI 적합성 인증기는 아닙니다.
주요 기능
- OpenAPI 3.0.x/3.1.x JSON·YAML의 경로와 HTTP 작업 목록 추출
- 경로 변수·필수 path 매개변수·중복 매개변수 점검
- 로컬 JSON Pointer 참조의 누락과 값 없는 순환 감지
- 응답 코드·description·본문 스키마 유무를 위치별로 표시
- 요청 본문 스키마에서 제한된 예시를 만들고 JSON 보고서 저장
사용 방법
- OpenAPI 3.0 또는 3.1 JSON/YAML 문서를 붙여넣거나 로컬 파일을 선택합니다.
- 검사를 실행해 오류와 경고의 JSON Pointer 위치를 확인합니다.
- 작업 목록에서 HTTP 메서드와 경로를 선택합니다.
- 생성된 요청 예시를 초안으로 검토하고 실제 인증·값을 채웁니다.
- 명세를 수정해 다시 검사하고 필요하면 보고서를 저장합니다.
활용 예시
- 경로 변수와 required path 매개변수 일치 여부 확인
- 컴포넌트 이름 변경 뒤 끊긴 로컬 참조 찾기
- 응답 설명과 JSON 본문 스키마 누락 검토
- 리뷰용 작업 목록과 요청 초안 공유
자주 묻는 질문
어떤 버전을 검사하나요?
OpenAPI 3.0.x와 3.1.x의 공통 핵심 계약을 대상으로 합니다. JSON/YAML 문법, 일부 경로·매개변수·참조·요청·응답 규칙을 검사합니다. 전체 명세 규칙, JSON Schema 어휘, 보안 요구사항의 적합성을 인증하지 않습니다.
외부 $ref를 따라가나요?
아니요. 같은 문서의 #/… JSON Pointer만 해석합니다. 외부 URL 또는 파일 참조는 경고로 표시하며 네트워크 요청을 하지 않습니다. 따라서 외부 참조가 있으면 완전한 검사 결과로 간주하지 마세요.
재귀 스키마는 오류인가요?
속성으로 자신을 가리키는 재귀 객체 스키마는 허용합니다. 값 없이 $ref만 다른 $ref로 이어지는 순환 별칭만 오류로 보고합니다.
생성한 요청 예시를 그대로 실행해도 되나요?
아니요. 이는 필수 속성과 기본형에 바탕을 둔 제한된 초안입니다. oneOf, 모든 직렬화 스타일, 인증, 서버 변수와 비즈니스 규칙을 채우지 않으며 네트워크로 전송하지 않습니다.
응답 content에 schema가 없으면 항상 잘못된 명세인가요?
아닙니다. 본문 제약을 확인할 수 없다는 경고입니다. 본문 자체가 없는 204 같은 응답에는 content가 없어도 경고하지 않습니다.
개인정보 안내
붙여넣거나 선택한 API 명세는 현재 브라우저 메모리에서만 처리합니다. 외부 참조를 다운로드하지 않고 API 서버에 요청을 보내지 않습니다. 사용자가 저장하는 보고서에는 경로와 진단 정보가 포함됩니다.
댓글과 질문