Echolot명세 편집
시각적 편집기나 YAML로 OpenAPI 문서를 설계합니다. 입력하는 동안 린트하고, 자동으로 저장하며, 실행 취소할 수 있습니다.
명세는 두 가지 방식으로 편집하며, 페이지 헤더의 편집기로 언제든 전환할 수 있습니다. 카드와 필드로 편집하는 시각적, YAML 또는 JSON 자체를 편집하는 코드입니다. 두 방식 모두 같은 텍스트를 바꿉니다. Echolot이 보관하는 것은 텍스트이므로, 시각적 편집은 편집한 부분의 줄만 바꿉니다. 그래서 주석, 순서, 서식이 그대로 유지되고 Git diff에서 무엇이 바뀌었는지 정확히 볼 수 있습니다.
명세를 시작하려면 사이드바의 명세 헤더에서 + › 새로운 명세를 선택하세요. Echolot이 제목이 New API인 OpenAPI 3.1 문서를
specs 폴더에 만들고 시각적 편집기에서 엽니다.
시각적 편집기
시각적 편집기의 필드는 편집을 마치면 문서를 바꿉니다. ↩를 누르거나 다른 필드로 이동하세요. 설명 필드는 Markdown을 받으며 ↩로 줄을 바꿉니다. 필드 옆의 버튼은 설명이 어떻게 읽힐지 보여 줍니다.
페이지에는 다음 카드가 있습니다.
| 카드 | 편집하는 내용 |
|---|---|
| 개요 | API의 제목, 버전, 설명. |
| 서버 | 서버의 URL과 설명. 서버 추가로 추가하고 −로 제거합니다. 서버가 없으면 명세에서 만든 요청은 직접 설정하는 {{baseUrl}}로 시작합니다. |
| 연락처 및 라이선스 | 보기를 누르면 연락처 이름, 이메일, URL, 라이선스와 그 URL, 서비스 약관이 열립니다. |
| 엔드포인트 | 모든 작업. 그룹화 기준은 경로 또는 태그로 나열합니다(태그가 없는 것은 태그 없음 아래). 클릭하면 열립니다. |
| 스키마 | 본문과 응답이 이름으로 참조할 수 있는 재사용 가능한 스키마. 클릭하면 열립니다. |
엔드포인트 추가
엔드포인트 카드에서 엔드포인트 추가를 클릭합니다. 새로운 엔드포인트 시트에서 메서드를 고르고 경로(예: /products/{sku})를
입력합니다. 요약과 태그는 선택 사항입니다. 그런 다음 엔드포인트 추가를 클릭하세요. Echolot이 경로의 매개변수를 정의하고, 시작점이 되는
본문과 성공 응답을 추가합니다. 이미 있는 메서드와 경로는 거부됩니다.
열려 있는 엔드포인트에는 다음이 있습니다.
| 부분 | 편집하는 내용 |
|---|---|
| 엔드포인트 | 메서드와 경로. 바꾸면 작업이 이동합니다. |
| 요약, 설명 | List products 같은 짧은 이름, 그리고 작업이 하는 일, 필요한 것, 반환하는 것. |
| 작업 ID, 태그 | 코드 생성기가 사용하는 ID, 그리고 쉼표로 구분한 태그. |
| 더 이상 사용되지 않음 | 작업을 더 이상 사용되지 않는 것으로 표시합니다. |
| 매개변수 | 각 매개변수의 이름, 위치(위치: path, query, header, cookie), 타입, 필수 여부, 설명. 매개변수 추가로 추가합니다. 경로에 정의되지 않은 매개변수가 있으면 {sku} 추가 같은 버튼으로 정의합니다. 경로 공통으로 표시된 매개변수는 경로의 모든 메서드에 대해 정의된 것입니다. |
| 요청 본문 | 본문 추가는 JSON 본문을 추가합니다. 각 미디어 타입에 스키마가 있고 본문을 필수로 지정할 수 있습니다. 본문 제거로 뺍니다. |
| 응답 | 상태 코드마다 한 행이 있으며 설명이 있고, 본문 추가 후에는 미디어 타입과 스키마도 있습니다. 응답 추가는 아직 사용하지 않은 다음 일반 코드(200, 201, 204, 400, 401, 403, 404, 409, 422, 500, 그다음 default)를 추가합니다. 코드를 편집해 바꿉니다. 작업에는 응답이 하나 이상 있어야 합니다. |
매개변수, 본문, 속성의 타입은 메뉴로 고릅니다. 재사용 가능한 스키마, string, integer, number, boolean, object, 이 중 어느 것의
배열, 또는 없음입니다. 메뉴로 표현할 수 없는 스키마는 작성된 그대로 표시되며, 다른 것을 고를 때까지 유지됩니다.
열려 있는 엔드포인트의 맨 아래에는 린트가 찾은 첫 번째 문제(포인터를 올리면 모든 문제가 보입니다)와 세 개의 버튼이 있습니다. 요청 열기(이 작업을 따르는 요청이 있을 때), 코드에서 보기, 엔드포인트 삭제입니다.
스키마 추가
스키마 카드에서 스키마 추가를 클릭하고 Product 같은 이름을 붙인 다음 추가를 클릭합니다. 열려 있는 스키마에는 이름,
설명, 속성이 있습니다. 속성은 각각 이름, 타입, 필수 여부, 설명이 있습니다. 속성 추가로 추가합니다.
스키마는 어디에서 사용되는지 알려 줍니다(3곳에서 사용됨 또는 아직 사용되지 않음). 이름을 바꾸면 모든 참조가 바뀝니다. 스키마가 사용 중일 때 스키마 삭제는 먼저 확인을 요청합니다. 그 참조가 아무것도 가리키지 않게 되기 때문입니다. 일반 객체가 아닌 스키마는 코드에서 설명하고 편집합니다. 코드에서 보기로 이동하세요.
Swagger 2.0
Swagger 2.0 문서는 시각적 편집기에서 읽기 전용으로 열리며, 편집은 코드에서 합니다. Echolot이 설계하는 것은 OpenAPI 3입니다.
코드 편집기
YAML 또는 JSON을 직접 편집하려면 편집기를 코드로 전환하세요. 린트는 입력하는 동안 잠시 멈추면 실행됩니다. 오류와 경고는 해당 줄에 밑줄로 표시되고, 포인터를 올리면 메시지가 나타납니다.
$ref 위에 포인터를 올리면 가리키는 대상이 보이고, ⌘-클릭하면 그곳으로 이동합니다. 다른 파일에 대한 참조는 그 파일을 엽니다.
명세가 참조하는 파일은 항상 코드로 열립니다.
텍스트를 구문 분석할 수 없으면 시각적 편집기에 시각적 편집기를 사용하려면 구문 분석할 수 있는 문서가 필요합니다.와 함께 줄과 오류가 표시됩니다. 코드에서 수정을 누르면 그 줄로 이동합니다.
저장
직접 저장할 필요는 없습니다. Echolot은 변경할 때마다 잠시 후, 그리고 다른 명세로 전환하거나 페이지를 떠나거나 윈도우를 닫을 때 명세를 기록합니다. 해당 명세의 실행 중인 모의 서버는 변경 사항을 반영합니다.
파일을 쓸 수 없으면(예: 읽기 전용이 된 경우) Echolot이 명세를 저장할 수 없음이라고 알리고 편집한 내용을 편집기에 그대로 둡니다.
| 버튼 | 하는 일 |
|---|---|
| 재시도 | 파일 쓰기를 다시 시도합니다. |
| 사본 저장… | 선택한 파일에 편집한 내용을 씁니다. |
| 변경 사항 폐기 | 디스크에 있는 파일 상태로 되돌립니다. |
| 계속 편집 | 메시지를 닫습니다. 편집한 내용은 유지되며, 저장될 때까지 페이지는 이 명세에 머뭅니다. |
실행 취소
편집 › 실행 취소(⌘Z)는 두 편집기 모두에서 편집을 취소하고, 편집 › 실행 복귀 (⇧⌘Z)는 되돌립니다. 시각적 편집은 하나가 한 단계이며, 입력은 잠시 멈출 때까지가 한 단계입니다. 실행 취소는 바꾼 명세에 속합니다. 다른 파일을 열고 나면 그 이전 파일에는 적용되지 않습니다.
에이전트와 함께
외부 에이전트에 대해 설정 › 에이전트에서 명세 도구 모음을 켜면 작업 공간의 명세를 읽고, 쓰고, 린트할 수 있습니다.