crank/docs/openapi-import.md

Импорт OpenAPI

Crank умеет импортировать REST API из OpenAPI 3.x и Swagger 2.0 документов. Импорт создает черновики MCP-инструментов, которые можно проверить и доработать в мастере операции перед публикацией.

Как импортировать

1. Откройте раздел Операции.
2. Нажмите Импорт OpenAPI рядом с кнопкой Новая операция.
3. Загрузите ровно один UTF-8 .yaml, .yml или .json файл размером от 1 B до 256 KiB. Вставка текста не поддерживается.
4. Нажмите Разобрать документ.
5. Проверьте preview: для каждого метода показываются поля Path, Query, Header, Body и поля ответа.
6. Выберите нужные группы и методы.
7. Проверьте Base URL. Если в документе нет servers, укажите URL вручную.
8. Выберите поведение при конфликте имени:
   • Создать копию с новым именем — Crank добавит суффикс _2, _3 и так далее.
   • Пропустить — существующие операции не будут изменены.
9. Нажмите Создать черновики.

Загрузка и восстановление

Браузер отправляет выбранный файл как multipart/form-data; границу multipart формирует сам браузер. Файл остаётся только в памяти текущего окна импорта. При замене файла, сбросе, закрытии окна, смене workspace/языка или уходе со страницы текущий запрос отменяется, а поздний ответ игнорируется. При pagehide (включая BFCache) выбранный файл и Base URL очищаются: после возврата нужно выбрать файл заново, повтор старой загрузки не предлагается.

Для ошибки можно выбрать файл заново или нажать Повторить. Диагностика показывает только ограниченные имя/размер файла и, если backend их вернул, Request ID/Trace ID; содержимое спецификации, digest, source ID и внутренние пути не выводятся. Повторное нажатие Создать черновики во время выполнения не создаёт вторую мутацию.

Что создается

Для каждого выбранного метода Crank создает отдельную операцию в статусе черновика:

• имя инструмента берется из operationId, а если его нет — строится из HTTP-метода и пути;
• отображаемое имя берется из summary;
• описание инструмента берется из description;
• группа берется из первого tag;
• query/path/header параметры становятся входными параметрами MCP-инструмента;
• JSON requestBody с объектной схемой раскладывается в отдельные входные поля;
• схема успешного ответа берется из 200, 201, 202 или default.

После импорта откройте созданный черновик в мастере операции. На шаге Связи полей Crank покажет уже созданный маппинг в визуальном виде:

• Path — параметры из пути, например /users/{id};
• Query — query-параметры URL;
• Header — заголовки запроса;
• Body — поля JSON-тела.

YAML-маппинг остается доступен в блоке Дополнительно, но для обычной настройки его редактировать не нужно.

Рекомендации

После разбора Crank показывает предупреждения, если в спецификации не хватает данных для качественного MCP-инструмента:

• нет operationId;
• нет summary или description;
• нет схемы успешного ответа;
• нет servers;
• слишком много входных параметров;
• используется тело запроса без JSON-схемы.

Эти предупреждения не блокируют импорт, но перед публикацией лучше открыть созданную операцию и проверить:

• описание инструмента;
• входные поля и их обязательность;
• связи Path / Query / Header / Body;
• пример входных данных для теста;
• поля ответа, которые увидит MCP клиент.

Ограничения Community

В Community импортируются только REST/HTTP методы: GET, POST, PUT, PATCH, DELETE.

Другие форматы спецификаций и протоколов в Community-импорт не входят.