feat(import): preserve supported HTTP contracts

This commit is contained in:
bsodfather committed 2026-09-13 03:30:31 +03:00
1 parent 083974c27f
commit f8ee7c9bfe
87 files changed
+7496 -534

No files matched your search

+16 -7
View File
@@ -8,7 +8,7 @@ Crank умеет импортировать REST API из OpenAPI 3.x и Swagger
2. Нажмите **Импорт OpenAPI** рядом с кнопкой **Новая операция**.
3. Загрузите ровно один UTF-8 `.yaml`, `.yml` или `.json` файл размером от 1 B до 256 KiB. Вставка текста не поддерживается.
4. Нажмите **Разобрать документ**.
5. Проверьте preview: для каждого метода показываются поля `Path`, `Query`, `Header`, `Body` и поля ответа.
5. Проверьте preview: сгенерированный contract сохраняет parameter locations, body formats и варианты успешного ответа.
6. Выберите нужные группы и методы.
7. Проверьте `Base URL`. Если в документе нет `servers`, укажите URL вручную.
8. Выберите поведение при конфликте имени:
@@ -30,16 +30,19 @@ Crank умеет импортировать REST API из OpenAPI 3.x и Swagger
- отображаемое имя берется из `summary`;
- описание инструмента берется из `description`;
- группа берется из первого `tag`;
- query/path/header параметры становятся входными параметрами MCP-инструмента;
- JSON `requestBody` с объектной схемой раскладывается в отдельные входные поля;
- схема успешного ответа берется из `200`, `201`, `202` или `default`.
- 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` — заголовки запроса;
- `Body` — поля JSON-тела.
- `Cookie` — cookie-параметры, которые adapter сериализует в один wire header;
- `Body` — typed тело запроса. Multipart file передаётся inline-объектом `{data_base64, filename?, content_type?}`; путь к файлу и URL не принимаются.
YAML-маппинг остается доступен в блоке **Дополнительно**, но для обычной настройки его редактировать не нужно.
@@ -52,7 +55,7 @@ YAML-маппинг остается доступен в блоке **Допол
- нет схемы успешного ответа;
- нет `servers`;
- слишком много входных параметров;
- используется тело запроса без JSON-схемы.
- требуется ручная проверка неполных metadata.
Эти предупреждения не блокируют импорт, но перед публикацией лучше открыть созданную операцию и проверить:
@@ -64,6 +67,12 @@ YAML-маппинг остается доступен в блоке **Допол
## Ограничения Community
В Community импортируются только REST/HTTP методы: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
В 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-импорт не входят.