EcholotСпецификация из ответов
Создание спецификации OpenAPI по отправленным вами запросам и полученным на них ответам.
Запросы у вас часто появляются раньше спецификации: коллекция, которую кто-то импортировал, или вызовы, которые вы пробовали, знакомясь с API. Спецификация из ответов превращает их в документ OpenAPI. Каждый запрос становится операцией, описанной по последнему полученному на него ответу: путь и параметры, отправленное тело, а также ответ со схемой JSON Schema его тела и примером. Добавляйте в уже существующую спецификацию, и она получит только то, чего ей не хватало.
Описание папки
Отправьте запросы, которые нужно описать, чтобы у каждого был ответ. В Alpenglow, например, отправьте запросы из папки Catalog.
Щёлкните папку в боковой панели «Запросы» правой кнопкой и выберите Описать в спецификации OpenAPI…. Чтобы описать всё рабочее пространство, выберите + › Новая спецификация из ответов… в боковой панели «Спецификации», Из ответов… на пустой странице «Спецификации» или Новая спецификация из ответов… в палитре команд.
В листе Описать в спецификации OpenAPI проверьте варианты:
| Вариант | Что значит |
|---|---|
| Запросы | Всё рабочее пространство или одна папка. Запросы её подпапок включаются. |
| Спецификация | Новая спецификация или спецификация рабочего пространства, в которую нужно добавить. Папка, которая уже следует спецификации, добавляет в неё. |
| Название | Название новой спецификации. Сначала это название папки или рабочего пространства. |
| Связать «папка» со спецификацией | По умолчанию включено. Запросы папки тогда следуют операциям, которыми стали, так что позднейшие изменения спецификации можно применять к ним. |
Нажмите Описать. Лист сообщит, что произошло, а Открыть спецификацию откроет результат.
Что получится
В результате перечислено:
| Заголовок | Что значит |
|---|---|
| Новые операции | Операции, которых в спецификации не было, например GET /products/{sku}. |
| Добавлен ответ | Операции, которые в ней были и теперь описывают ещё один ответ, например 404. |
| Уже описаны | Операции, которые она уже описывала так, как на них ответили. Ничего не изменилось. |
| Не вошло | Запросы, которые не были описаны, у каждого указана причина. |
Там же сказано, сколько запросов теперь следуют своим операциям и сколько ошибок линтер находит в результате, если находит.
Что попадает в каждую операцию:
- Путь в форме OpenAPI: сегменты пути, пришедшие из переменных, становятся параметрами пути, описанными с отправленными значениями. Серверная часть URL в путь не входит.
- Параметры запроса и заголовки, которые задаёт запрос.
- Тело запроса и ответ со схемой JSON Schema, созданной по телу, и примером. Большие примеры опускаются, а схема остаётся; в длинных массивах пример сохраняет несколько элементов.
- имя запроса как сводка операции, а его подпапка как тег операции.
- Авторизация запроса как схема безопасности. Если в OpenAPI для неё нет схемы (OAuth 2 с типом предоставления device code), об этом сообщает примечание.
Секреты скрываются: секретные переменные и значения под ключами, похожими на секретные (токены, пароли, ключи),
выглядят в примерах как ••••••.
Добавление в существующую спецификацию
Выберите спецификацию в поле Спецификация. Echolot добавляет только то, чего не хватает: операции, ответы, схемы и схемы безопасности, которые в ней ещё не названы. То, что в спецификации уже сказано, остаётся как написано. Спецификации в Swagger 2.0 дополнять нельзя; только документы OpenAPI 3.
Описание отдельных ответов из истории
В Истории щёлкните правой кнопкой HTTP-обмен, на который пришёл ответ, и выберите Добавить в спецификацию OpenAPI…. Откроется тот же лист, но для одного этого ответа. Это удобно для ответа, который вы увидели один раз, например ошибки.
Что не вошло
- Запросы не HTTP (GraphQL, gRPC, WebSocket и прочие): в OpenAPI описываются только HTTP-запросы.
- Запросы, на которые ещё нет ответа: сначала отправьте их.
- Запросы, отправка которых завершилась ошибкой до получения ответа.
- Запросы в подпапке, которая следует собственной спецификации.
Поддержание актуальности
Когда папка следует спецификации, контрактом становится спецификация. Правьте её на странице «Спецификации» и применяйте изменения к запросам через Проверить изменения для «папка»…. См. Запросы, которые следуют спецификации. Ответы спецификации можно также отдать моку, чтобы фронтенд мог работать с ней.
Агенты могут делать то же через инструмент add_to_spec, когда включён набор инструментов Спецификации: см.
Агенты.