70 lines
5.6 KiB
Markdown
70 lines
5.6 KiB
Markdown
# Импорт 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-импорт не входят.
|