Files
crank/docs/openapi-import.md
T

79 lines
8.0 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. Выберите поведение при конфликте имени:
- **Создать копию с новым именем** — 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/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-импорт не входят.