명세

명세 페이지는 API의 계약을 설계하고 보관하는 곳입니다. OpenAPI 문서(OpenAPI 3.0, 3.1, Swagger 2.0)와 gRPC 서비스의 .proto 파일을 다룹니다. Echolot은 편집하는 동안 명세를 검사하고, 명세와 보조를 맞추는 요청으로 바꾸며, API가 만들어지기 전에 명세를 모의 서버로 제공합니다.

사이드바의 모듈 전환기에서 명세를 선택하거나 ⌘3을 눌러 엽니다.

작업 공간의 명세Copy Anchor Link

명세는 작업 공간의 specs 폴더에 있는 파일이므로 다른 모든 것과 함께 Git에 들어갑니다. Alpenglow 예제에는 alpenglow.yaml(쇼핑몰의 OpenAPI 문서), shop.graphql, inventory.proto 세 개가 있습니다. 명세 페이지는 OpenAPI 문서를 명세 아래에, .proto 파일을 Proto 파일 아래에 나열합니다. 폴더에 있는 GraphQL 스키마는 GraphQL 요청이 사용하며 여기에는 나열되지 않습니다.

사이드바의 명세 헤더에 있는 +로 추가합니다.

파일 › 가져오기…로 OpenAPI 문서를 가져오는 것은 다릅니다. 편집할 명세가 아니라 문서에서 요청을 만듭니다.

명세를 오른쪽 클릭하면 요청 생성, Finder에서 보기, 내보내기(YAML로… 또는 JSON으로…), 삭제…가 나타납니다. 삭제하기 전에 확인을 요청하며 파일을 휴지통으로 이동합니다. 명세가 참조하는 파일과 명세의 모의 서버는 그대로 남습니다.

개요Copy Anchor Link

명세를 클릭해서 엽니다. 목록 아래 사이드바에 명세의 개요가 표시됩니다.

• 개요: 제목, 버전, 설명.
• 엔드포인트: 메서드와 경로가 있는 모든 작업. 더 이상 사용되지 않는 것은 취소선으로 표시됩니다. 포인터를 올리면 요약이 표시됩니다.
• 스키마: 재사용할 수 있는 스키마.
• 파일: 명세가 다른 파일을 참조할 때(파일로 나눈 명세 참고).

항목을 클릭하면 열립니다. 시각적 편집기에서는 해당 카드가 열리고 화면으로 스크롤되며, 코드에서는 편집기가 해당 줄로 이동합니다.

시각적 편집과 코드Copy Anchor Link

페이지 헤더의 편집기 스위치로 열려 있는 명세를 보는 방식을 고릅니다.

• 시각적: 개요, 서버, 엔드포인트, 스키마 카드를 필드와 메뉴로 편집합니다.
• 코드: 줄 번호가 있는 YAML 또는 JSON 문서.

두 방식 모두 같은 텍스트를 편집하며, Echolot은 변경할 때마다 잠시 후 저장합니다. 두 방식은 명세 편집에서 다룹니다.

문제Copy Anchor Link

Echolot은 편집하는 동안 명세를 린트합니다. 편집기 위의 막대에 문제 없음이나 오류와 경고의 수가 표시됩니다. 사이드바에서 열려 있는 명세 옆에도 오류 수가 빨간색으로 표시됩니다.

클릭하면 목록이 표시됩니다. 오류가 먼저 나오고 그다음에 경고와 힌트가 줄 번호와 함께 나옵니다. 하나를 선택하면 그 줄로 이동합니다. 목록이 비어 있으면 문서가 OpenAPI 사양을 따르며 모든 참조가 해결된다고 표시됩니다.

린트가 확인하는 것은 다음과 같습니다.

• Echolot이 읽을 수 있는 openapi 버전, 제목과 버전이 있는 info, /로 시작하는 경로.
• 경로에 있고 required: true로 표시된 경로 매개변수, 그리고 두 번 정의되지 않은 매개변수.
• 모든 응답의 설명, 한 번만 사용된 작업 ID.
• 맨 위에 선언된 태그, 정의된 보안 스킴, items가 있는 배열, 값이 있는 열거형.
• 이 파일이나 specs의 다른 파일에서 무언가를 가리키는 참조.
• servers가 없는 경우: 명세에서 만든 요청은 직접 설정하는 {{baseUrl}}로 시작합니다.

명령줄 도구는 CI에서 같은 린트를 실행합니다. echolot spec을 참고하세요.

파일로 나눈 명세Copy Anchor Link

명세는 $ref: schemas/pet.yaml#/Pet처럼 $ref로 다른 파일의 일부를 가져올 수 있습니다. 파일은 작업 공간의 specs 폴더 안에 있어야 합니다. 사이드바의 파일 아래에 나열되며, 클릭하면 코드에서 열립니다. 코드 편집기에서 $ref 위에 포인터를 올리면 가리키는 대상이 보이고, ⌘-클릭하면 이 파일이든 다른 파일이든 그곳으로 이동합니다.

Echolot은 린트, 요청 생성, 모의 서버처럼 명세를 사용하는 모든 곳에서 부분들을 함께 읽습니다. 명세를 내보내면 참조하는 파일이 저장하는 하나의 파일 안에 함께 기록됩니다.

내보내기Copy Anchor Link

편집기 위 막대의 내보내기(YAML로 내보내기… 또는 JSON으로 내보내기…)는 명세를 작업 공간 밖의 파일 하나로 저장하며, 참조하는 파일이 그 안에 기록됩니다. 저장하지 않은 편집은 먼저 저장되므로 내보내는 내용은 편집기에 표시된 내용과 같습니다.

명세를 따르는 요청Copy Anchor Link

편집기 위 막대의 요청 생성은 명세의 이름으로 된 폴더를 만들고 모든 엔드포인트에 대한 요청을 넣은 다음 첫 번째 요청을 엽니다. 폴더는 명세를 따릅니다. 명세가 바뀌면 요청에서 직접 편집한 내용을 잃지 않고 변경 사항을 요청에 적용할 수 있습니다.

폴더가 명세를 따르게 되면 버튼이 요청으로 바뀌며, 명세를 따르는 각 폴더에 대한 “폴더 이름” 폴더의 변경 사항 확인…과 다른 폴더 생성이 들어 있는 메뉴가 됩니다. 확인하면 OpenAPI 동기화가 열리고 명세에 새로 추가됨, 명세에서 변경됨, 명세에서 사라짐이 나열됩니다. 원하는 변경 사항을 선택하고 변경 사항 1개 적용(또는 변경 사항 3개 적용 등)을 클릭하세요. 직접 편집한 내용은 항상 유지되며, 직접 바꾼 것과 명세가 바뀐 것이 같은 항목이면 직접 바꾼 쪽이 유지됩니다. 작업이 사라지면 그 요청은 휴지통으로 이동합니다. 단, 직접 편집한 요청은 그대로 남고 명세를 따르지 않게 됩니다. 연결 해제는 폴더가 명세를 따르지 않게 하고 요청은 그대로 둡니다.

폴더가 작업 공간 밖의 파일이나 URL에 있는 명세를 따르게 할 수도 있습니다. 요청 사이드바에서 폴더를 오른쪽 클릭하고 OpenAPI 명세에 연결…을 선택하세요. 명령줄 도구는 echolot spec check와 echolot spec apply로 변경 사항을 확인하고 적용합니다.