OpenAPI 동기화
Free Rider의 OpenAPI 연결은 컬렉션 내부에서 관리합니다. 새 컬렉션을 만들 때 OpenAPI로 시작하기를 선택할 수도 있으며, 동기화는 명세를 즉시 덮어쓰지 않고 변경을 먼저 검토한 뒤 선택적으로 반영합니다.
지원 입력
- OpenAPI 3.x JSON 파일
- OpenAPI 3.x YAML 파일
- HTTP/HTTPS URL
외부 $ref가 있는 명세는 먼저 bundle한 뒤 가져옵니다.
동기화 흐름
- 연결 — OpenAPI 파일 또는 URL을 연결합니다.
- 동기화 — 변경 검토 목록을 만듭니다. 이 단계에서는 요청이 바뀌지 않습니다.
- 비교 — 엔드포인트를 펼쳐 이전 명세 / 현재 요청 / 새 명세를 비교합니다.
- 호환성 확인 — 기존 호출이나 응답 처리를 깨뜨릴 수 있는 변경을
BREAKING으로 표시합니다. - 충돌 해결 — 현재 값 유지 또는 명세 값 반영을 선택합니다.
- 선택 반영 — 체크한 엔드포인트만 반영합니다. 삭제 후보는 기본 미선택입니다.
- 저장과 복원 — 저장 성공 후 변경을 적용하며 직전 반영 상태를 복원할 수 있습니다.
미해결 충돌이 남아 있으면 반영할 수 없습니다.
Breaking Change 감지
동기화 검토에서 다음과 같은 호환성 위험을 적용 전에 표시합니다.
- 기존 operation 삭제
- 새 필수 파라미터 추가 또는 기존 파라미터의 필수 전환
- 요청 파라미터 / Body 스키마 타입 변경 또는 enum 허용 값 축소
- 요청 Body 또는 객체 속성의 필수 전환
- 기존 2xx 성공 응답 또는 응답 미디어 타입 삭제
- 기존 응답 속성 삭제 또는 응답 스키마 타입 변경
BREAKING 표시는 변경을 자동으로 차단하지 않습니다. 이유를 확인하고 필요한 엔드포인트만 선택해 반영하세요. 삭제 후보는 기존과 동일하게 기본 선택하지 않습니다.
비교 단위
Headers, Query, 응답 스키마는 항목별로 비교합니다. 문자열 Body와 배열은 하나의 값으로 비교합니다.
선택하지 않은 변경은 다음 동기화에서도 계속 남아 있으므로 한 번에 모든 변경을 처리할 필요는 없습니다.
명세 파일 다시 읽기
연결한 파일을 외부 편집기에서 수정했다면 다시 읽기로 최신 내용을 불러와 재검토합니다.
서버 주소와 Environment
선택한 Environment의 baseUrl이 비어 있으면 명세의 server URL을 등록하도록 제안할 수 있습니다.
URL로 가져온 명세에서 상대 server URL을 사용하면 명세 URL을 기준으로 해석합니다.
Basic Auth로 보호된 명세 가져오기
새 컬렉션의 OpenAPI로 시작하기 또는 기존 컬렉션의 OpenAPI / API Specifications에서 URL을 입력한 다음, Specification authentication → Basic Auth를 선택하고 Username과 Password를 입력하세요. URL로 시작 또는 Synchronize로 JSON/YAML 명세를 불러옵니다. 비밀번호 옆 눈 버튼으로 값을 확인할 수 있습니다.
이 인증은 명세 파일 다운로드 전용이며, 생성된 API 요청의 Auth와 별개입니다. 인증 정보는 같은 컬렉션과 URL에서 앱 실행 중에만 재사용하고, URL 변경 또는 앱 종료 시 삭제합니다. 워크스페이스 저장, 컬렉션 Export, Git 공유에는 포함되지 않습니다. 재실행 후에는 다시 입력하세요.
HTTP 401은 아이디/비밀번호를, HTTP 403은 명세 접근 권한을 확인하세요. URL에 user:password@를 넣지 말고 인증 입력란을 사용하세요. HTTPS 사용을 권장하며, 리다이렉트는 기존과 동일하게 허용하지 않습니다.