가져온 API 문서 열람 및 업데이트

명세를 가져오면 Restorm은 요청만 만들어 내는 것이 아닙니다. API 문서, 즉 설명, 모델, 보안 스키마, 예시, 열거형까지 그대로 보존해서 가져오기로 생성된 변수 폴더에 첨부합니다.

문서에 접근하기

변수 폴더의 문서 탭

이것이 기본 화면입니다. 가져오기로 만들어진 변수 폴더를 여십시오. 하위 탭 바에 환경, Custom variables, 메모 와 나란히 문서 탭이 있습니다.

이 탭은 폴더가 가져오기로 만들어진 경우에만 나타납니다. 직접 만든 변수 폴더에는 표시할 문서가 없습니다.

그 밖의 진입점

위치	표시되는 내용
요청의 문서 탭	해당 작업 하나만의 문서. 목차나 전체 정보 블록은 없습니다. 명세에서 그 작업을 찾은 경우에만 나타납니다
일반 폴더의 문서 탭	그 폴더에 들어 있는 작업으로 한정된 문서
변수 폴더의 시작 하위 탭	문서 보기 카드 — “API 문서, 모델, 엔드포인트를 살펴봅니다”
시작 화면 (API 카드)	빠른 링크 문서
타이틀 바의 검색 바	검색 결과에 마우스를 올리면 문서 미리 보기가 나타납니다

화면에 담기는 내용

위에서 아래로 다음 순서입니다.

• API의 제목과 그 설명
• 정보 블록: Version, Source format (원본 URL 링크 포함), Server (스킴, 호스트, 기본 경로), Contact, License, Terms of service, External docs
• 태그별 섹션과 그 설명
• 작업별 블록: 메서드와 URL, 요약, 그룹 배지, 해당하는 경우 deprecated 배지, Security 섹션 (스키마 종류, OAuth 2 플로, 스코프), 그리고 접을 수 있는 Example payload
• Parameters 와 Responses 표 (상태 코드는 색으로 구분됩니다)
• Models — 스키마의 대화형 그래프. 이동과 확대/축소가 가능합니다.
• Polymorphism — oneOf / anyOf / allOf 조합
• Enums — 열거형. 폴더 쪽 열거형과 병합됩니다.

Note

이 섹션 제목들 (Models, Enums, Parameters, Responses, Security, Example payload) 은 애플리케이션의 언어 설정과 무관하게 영어로 표시됩니다. 화면과 대조하기 쉽도록 여기서도 그대로 적었습니다.

문서에서 요청 만들기

각 작업 블록에는 + Add 버튼이 있어, 그 작업에 맞게 미리 설정된 요청을 만들어 줍니다. 가져오기가 일부만 이루어졌을 때, 또는 명세에 새 작업이 막 추가되었을 때 가장 빠른 방법입니다.

이동과 검색

오른쪽에는 목차가 고정되어 있으며 — Overview, Operations, Models, Enums 섹션 — 접기와 크기 조절이 가능합니다. 모델을 클릭하면 그래프까지 스크롤되고 해당 노드가 화면 중앙에 놓입니다.

단축키	효과
Ctrl+F / Cmd+F	문서 내 검색을 엽니다
F3 / Enter	다음 일치 항목
Shift+F3 / Shift+Enter	이전 일치 항목
Esc	검색을 닫습니다

카운터가 검색 결과 안에서의 위치를 알려 줍니다.

문서 업데이트하기

명세는 계속 바뀝니다. Restorm은 원본을 다시 가져와 문서 와 요청 양쪽에 차이만 적용할 수 있으며, 작업해 둔 내용을 덮어쓰지 않습니다.

URL로 가져온 경우에만

재동기화는 폴더를 URL에서 가져온 경우에만 사용할 수 있습니다. 파일에서 가져오거나 붙여넣기로 가져온 경우에는 원본이 기록되지 않으므로 새로 고침 버튼이 나타나지 않고, 시작 하위 탭에는 “이 폴더는 가져올 수 있는 소스에서 생성되지 않았습니다.” 라고 표시됩니다.

이 URL은 나중에 인터페이스에서 변경할 수 없습니다. 원본을 바꾸려면 다시 가져오십시오.

버튼의 위치

동등한 진입점이 두 곳 있습니다.

1. 변수 폴더의 시작 하위 탭에 있는 API 명세 업데이트 섹션. URL, 마지막으로 가져온 시각, 마지막으로 확인한 시각 이 표시되며 새로 고침 버튼이 있습니다.
2. 사이드 트리에서 폴더를 오른쪽 클릭 → 새로 고침.

자동 확인은 없습니다

Restorm은 백그라운드에서 명세를 감시하지 않으며, 새 버전이 나왔다고 알려 주지도 않습니다. 확인은 항상 사용자가 직접 시작합니다.

어떤 일이 일어나는가

1. 가져오는 동안 “API 명세를 새로 고치는 중…” 창이 나타납니다. URL과 헤더에 들어 있는 {{variables}} 는 해석되고, 첨부된 인증 경로가 먼저 실행됩니다.
2. Restorm은 가져온 원본의 지문을 지난번 가져오기 때 기록해 둔 값과 비교합니다.
3. 바뀐 것이 없으면 → “API 명세가 최신 상태입니다.” 가 표시되고 그대로 끝납니다.
4. 바뀐 것이 있으면 (또는 가져오기가 실패하면) → 재동기화 마법사가 열립니다.

마법사

• 원본 URL은 읽기 전용으로 표시됩니다.
• 배지에서 인증 경로를 첨부하거나 변경하거나 분리 할 수 있고, Custom headers 하위 메뉴에서 새로 고침마다 다시 전송되는 고정 헤더를 추가할 수 있습니다.
• 미리 보기 탭이 두 개 있습니다.
  • Routes — 새 버전에서 찾은 작업들의 트리로, 필터와 선택을 지원합니다. 폴더에 이미 있는 작업은 잠긴 상태로 항상 선택되어 있으며, 고를 수 있는 것은 추가할 새 작업뿐입니다.
  • Documentation — 새 버전의 문서. 확정하기 전에 읽기 전용으로 확인할 수 있습니다.
• 확인 버튼에는 선택한 새 작업의 개수가 표시됩니다. 예를 들면 **Apply update (3)**입니다.

Note

이 마법사는 현재 애플리케이션의 언어 설정과 무관하게 영어로 표시됩니다 (“Refresh from source”, “Apply update”, 그리고 “Routes” 와 “Documentation” 탭). 그래서 여기서도 영어 표기를 그대로 실었습니다.

무엇이 바뀌고, 무엇이 바뀌지 않는가

여기가 핵심입니다. 명세는 자신이 기술하는 범위에 대해 권위를 가지며, 그 밖의 모든 것에 대해서는 사용자에게 결정권이 있습니다.

요소	동작
요청의 이름	절대 변경되지 않습니다
메서드와 URL	절대 변경되지 않습니다
기존 파라미터, 헤더, 경로 파라미터	값, 설명, 활성화 상태가 그대로 유지됩니다
명세가 추가한 파라미터	추가됩니다. 값은 명세의 기본값이거나 비어 있습니다
명세에서 삭제된 파라미터	요청에 그대로 남습니다
새 작업	새로 가져왔다면 놓였을 위치에 추가됩니다 (태그 폴더까지 포함)
명세에서 더 이상 사용되지 않음으로 표시된 작업	표시가 붙고, 트리에서 흐리게 나타납니다
명세에서 사라진 작업	삭제된 것으로 표시되어 트리에서 취소선이 그어지지만, 계속 실행할 수 있고 절대 삭제되지 않습니다
API 문서와 열거형	새 버전으로 전부 교체됩니다. 이것이 문서 탭을 새로 고쳐 주는 동작입니다

트리에서 무언가가 삭제되는 일은 결코 없습니다. 원본에서 사라진 작업에는 표시만 붙고, 지워지지는 않습니다.

원본이 인증을 요구하는 경우

응답이 401 또는 403 이면, 오류 메시지 (예: HTTP 401: Unauthorized) 를 그대로 표시한 상태로 마법사가 열립니다. 인증 경로를 첨부하거나 고정 헤더를 추가하면 미리 보기가 다시 실행됩니다.

재동기화가 가능한 형식

재동기화를 지원하는 형식은 12 가지입니다. Swagger 2.0, OpenAPI 3.x, GraphQL, gRPC, SOAP (WSDL), OData, AsyncAPI, Postman, Insomnia, Bruno, OpenRPC, Smithy 입니다.

그 밖의 모든 형식에서는 다시 가져오면 새 트리가 만들어집니다. 전체 목록은 원본에서 업데이트하기에 있습니다.