EcholotПравка спецификации
Проектирование документа OpenAPI в визуальном редакторе или в YAML, с линтером при вводе, сохранением и отменой.
Спецификацию можно править двумя способами и переключаться между ними в любой момент с помощью Редактор в заголовке страницы: Визуально — карточки и поля, Код — сам YAML или JSON. Оба режима меняют один и тот же текст. Именно текст и хранит Echolot: визуальная правка меняет только строки той части, которую вы правили, поэтому комментарии, порядок и форматирование сохраняются, а дифф Git показывает ровно то, что изменилось.
Чтобы начать спецификацию, выберите + › Новая спецификация в заголовке Спецификации боковой панели. Echolot
записывает в папку specs документ OpenAPI 3.1 с названием New API и открывает его в визуальном редакторе.
Визуальный редактор
Поля визуального редактора изменяют документ, когда вы заканчиваете их правку: нажмите ↩ или перейдите в другое поле. Поля описания принимают 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) возвращает их. Каждая визуальная правка — один шаг; набор текста — один шаг, пока вы не сделаете паузу. Отмена относится к той спецификации, которую изменила: когда вы открываете другой файл, она не затрагивает предыдущий.
С агентом
Внешние агенты могут читать, записывать и проверять спецификации рабочего пространства, если вы включите для них набор инструментов Спецификации в Настройки › Агенты.