Спецификации

Страница «Спецификации» — это место, где вы проектируете и храните контракт API: документы OpenAPI (OpenAPI 3.0 и 3.1 и Swagger 2.0) и файлы .proto сервисов gRPC. 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 и все ссылки разрешаются.

Что, среди прочего, проверяет линтер:

• Версию openapi, которую понимает Echolot, info с названием и версией и пути, начинающиеся с /.
• Параметры пути, которые есть в пути и помечены required: true, и параметры, которые не определены дважды.
• Описание у каждого ответа и идентификаторы операций, которые встречаются один раз.
• Теги, объявленные наверху, определённые схемы безопасности, массивы с items и перечисления со значениями.
• Ссылки, которые на что-то указывают, в этом файле или в другом файле из specs.
• Отсутствие servers: тогда созданные из спецификации запросы начинаются с {{baseUrl}}, которую вы задаёте сами.

Утилита командной строки запускает тот же линтер в CI: см. echolot spec.

Спецификации из нескольких файловCopy Anchor Link

Спецификация может подключать части других файлов через $ref, например $ref: schemas/pet.yaml#/Pet. Файлы должны находиться внутри папки specs рабочего пространства. Боковая панель перечисляет их в разделе Файлы: щёлкните файл, чтобы открыть его в режиме Код. В редакторе кода наведите указатель на $ref, чтобы увидеть, на что он указывает, и щёлкните по нему с нажатой клавишей ⌘, чтобы перейти туда, в этом файле или в другом.

Echolot читает части вместе везде, где использует спецификацию: в линтере, при создании запросов, в моках. При экспорте спецификации файлы, на которые она ссылается, записываются в один сохраняемый вами файл.

ЭкспортCopy Anchor Link

Экспорт на панели над редактором (Экспортировать как YAML… или Экспортировать как JSON…) сохраняет спецификацию одним файлом вне рабочего пространства, записывая в него файлы, на которые она ссылается. Несохранённые правки сначала сохраняются, так что экспорт — это то, что показывает редактор.

Запросы, которые следуют спецификацииCopy Anchor Link

Создать запросы на панели над редактором создаёт папку с названием спецификации и запросом для каждого эндпоинта и открывает первый. Папка следует спецификации: когда спецификация меняется, можно применить изменения к её запросам, не потеряв того, что вы в них правили.

Когда папка следует спецификации, кнопка превращается в Запросы — меню с пунктом Проверить изменения для «папка»… для каждой папки, которая ей следует, и пунктом Создать ещё одну папку. Проверка открывает Синхронизацию OpenAPI, где перечислено, что Новое в спецификации, Изменено в спецификации и Удалено из спецификации. Отметьте нужные изменения и нажмите Применить 1 изменение (или Применить 3 изменения и так далее). Ваши правки всегда остаются; если вы и спецификация изменили одно и то же, сохраняется ваш вариант. Когда операция исчезла, её запрос перемещается в Корзину, если только вы его не правили: тогда он остаётся и перестаёт следовать спецификации. Отвязать прекращает следование папки спецификации и оставляет её запросы как есть.

Папка может следовать и спецификации вне рабочего пространства — файлу или URL: щёлкните папку в боковой панели «Запросы» правой кнопкой и выберите Связать со спецификацией OpenAPI…. Утилита командной строки проверяет и применяет изменения командами echolot spec check и echolot spec apply.