Files
crank/docs/openapi-import.md
T

84 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Импорт 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: сгенерированный contract сохраняет parameter locations, body formats и варианты успешного ответа.
6. Выберите нужные группы и методы.
7. Проверьте `Base URL`. Если в документе нет `servers`, укажите URL вручную.
8. Для уже существующей операции подтвердите решение отдельно: пропустить точную операцию, создать отдельную операцию с указанным вами свободным именем или добавить новую черновую версию к выбранной REST-операции. Автоматический подбор имени при применении плана не выполняется.
9. Создайте план и проверьте число выбранных, исключённых, доступных и заблокированных методов. По умолчанию полный план требует, чтобы каждый метод можно было применить; для частичного импорта явно оставьте только нужные методы.
10. Подтвердите план и примените его. Создание плана не меняет операции. Применение выполняет все выбранные изменения одной транзакцией и показывает результат для каждого метода.
## Загрузка и восстановление
Браузер отправляет выбранный файл как `multipart/form-data`; границу multipart формирует сам браузер. Файл остаётся только в памяти текущего окна импорта. При замене файла, сбросе, закрытии окна, смене workspace/языка или уходе со страницы текущий запрос отменяется, а поздний ответ игнорируется. При `pagehide` (включая BFCache) выбранный файл и Base URL очищаются: после возврата нужно выбрать файл заново, повтор старой загрузки не предлагается.
Для ошибки можно выбрать файл заново или нажать **Повторить**. Диагностика загрузки показывает только ограниченные имя/размер файла и, если backend их вернул, `Request ID`/`Trace ID`; содержимое спецификации и внутренние пути не выводятся. Подтверждение плана показывает счётчики и решения по кандидатам, но не исходный документ и не учётные данные. Digest плана передаётся в Apply автоматически.
При неизвестном результате Apply, например после разрыва соединения, повторите запрос с теми же ссылкой на план, digest и ключом идемпотентности. Повтор после commit возвращает сохранённый отчёт и не создаёт ещё одну версию; тот же ключ с другим digest даёт конфликт. Пока Apply выполняется, повторное нажатие кнопки не отправляет вторую логическую операцию.
Если с момента создания плана изменились источник или внешние документы, версия импортера либо состояние выбранной операции, а также конфигурация выбранного Auth Profile или версия его секрета, Apply отклоняет план без частичных изменений и предлагает заново разобрать документ. Отозванный или недоступный профиль также приводит к отказу. Срок жизни плана ограничен сроком исходного preview job.
## Что создается
Для каждого нового выбранного метода Crank создает отдельную операцию в статусе черновика. Для `new_version` новая Draft Version добавляется к точно выбранной операции; текущая опубликованная версия, прежние версии, привязки и история остаются прежними. `skip` не меняет выбранную существующую операцию. Исключённые методы не создаются, но перечисляются в отчёте.
Контракт нового черновика:
- имя инструмента берется из `operationId`, а если его нет — строится из HTTP-метода и пути;
- отображаемое имя берется из `summary`;
- описание инструмента берется из `description`;
- группа берется из первого `tag`;
- query/path/header/cookie параметры становятся отдельными typed inputs MCP-инструмента;
- JSON, `application/x-www-form-urlencoded` и `multipart/form-data` сохраняются как request contract; при нескольких поддерживаемых форматах вызов передаёт верхнеуровневые `content_type` и `body`;
- все успешные `2xx` варианты сохраняются, включая `204` и response без тела.
Form/multipart поддерживает object root со scalar-полями, массивами scalar-значений и multipart files. Вложенные обычные объекты и массивы массивов блокируют импорт. Для URL-encoded массивов поддержана повторная передача ключей (`style: form`, `explode: true`; в Swagger — `collectionFormat: multi`). CSV и другие неподдерживаемые encoding-настройки получают blocker с указанием места в исходной спецификации.
После импорта откройте созданный черновик в мастере операции. На шаге **Связи полей** Crank покажет уже созданный маппинг в визуальном виде:
- `Path` — параметры из пути, например `/users/{id}`;
- `Query` — query-параметры URL;
- `Header` — заголовки запроса;
- `Cookie` — cookie-параметры, которые adapter сериализует в один wire header;
- `Body` — typed тело запроса. Multipart file передаётся inline-объектом `{data_base64, filename?, content_type?}`; путь к файлу и URL не принимаются.
YAML-маппинг остается доступен в блоке **Дополнительно**, но для обычной настройки его редактировать не нужно.
## Рекомендации
После разбора Crank показывает предупреждения, если в спецификации не хватает данных для качественного MCP-инструмента:
- нет `operationId`;
- нет `summary` или `description`;
- нет схемы успешного ответа;
- нет `servers`;
- слишком много входных параметров;
- требуется ручная проверка неполных metadata.
Эти предупреждения не блокируют импорт, но перед публикацией лучше открыть созданную операцию и проверить:
- описание инструмента;
- входные поля и их обязательность;
- связи `Path / Query / Header / Body`;
- пример входных данных для теста;
- поля ответа, которые увидит MCP клиент.
## Ограничения Community
В Community импортируются только REST/HTTP методы: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`. `TRACE` и `CONNECT`, XML media types и неподдерживаемые serialization constructs получают явный finding и не получают неявного fallback.
Semantic loss получает blocker с source location: такой candidate нельзя применить как actionable Draft. Это относится к неподдерживаемым schema/serialization constructs и невалидным target URL, включая embedded userinfo.
Один endpoint с несколькими request formats остаётся одним Tool. Поля `content_type` и `body` выбирают одну schema и соответствующую сериализацию; неизвестный selector или body другой ветви отклоняются до отправки запроса. Для единственного формата selector не нужен. Подробный inline-file contract описан в [REST](protocols/rest.md).
Новые imports используют `normalized-ir-v4` / `preview-v4`. Сохранённые v2/v3 jobs воспроизводят сохранённый preview, а legacy-v1 использует отдельную историческую projection. Обновление importer не меняет inputs существующих jobs.
Другие форматы спецификаций и протоколов в Community-импорт не входят.