Files
crank/docs/openapi-import.md
T

89 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. Выберите поведение при конфликте имени:
- **Создать копию с новым именем** — Crank добавит суффикс `_2`, `_3` и так далее.
- **Пропустить** — существующие операции не будут изменены.
9. Нажмите **Создать черновики**.
## Загрузка и восстановление
Браузер отправляет выбранный файл как `multipart/form-data`; границу multipart формирует сам браузер. Файл остаётся только в памяти текущего окна импорта. При замене файла, сбросе, закрытии окна, смене workspace/языка или уходе со страницы текущий запрос отменяется, а поздний ответ игнорируется. При `pagehide` (включая BFCache) выбранный файл и Base URL очищаются: после возврата нужно выбрать файл заново, повтор старой загрузки не предлагается.
Для ошибки можно выбрать файл заново или нажать **Повторить**. Диагностика показывает только ограниченные имя/размер файла и, если backend их вернул, `Request ID`/`Trace ID`; содержимое спецификации, digest, source ID и внутренние пути не выводятся. Повторное нажатие **Создать черновики** во время выполнения не создаёт вторую мутацию.
## Контракт API импорта и аутентификация
В workspace API доступны `POST /imports/openapi/preview` (multipart upload) и `POST /imports/openapi/{job_id}/create` (JSON). Preview сохраняет effective security requirements по операциям и предлагает `auth_profile_choices`: для каждой OR-alternative он указывает индекс, имена схем, признак `supported` и только совместимые профили текущего workspace. Варианты профиля содержат ID, имя и тип; значения Secret и другие credential material не возвращаются.
При создании черновиков отправляйте `auth_mappings` с одной записью на выбранную защищённую операцию: `{ "operation_key": "GET /items", "alternative_index": 0, "auth_profile_id": "auth_…" }`. `alternative_index` начинается с нуля. Внешний список security alternatives означает OR; все схемы внутри одной alternative означают AND. Текущий runtime применяет одну Auth Profile, поэтому неподдерживаемый AND-вариант нельзя выбрать. Для явно пустой alternative можно передать `auth_profile_id: null`; отсутствие mappings остаётся совместимым для операций без security requirements. Неуказанное или unresolved required mapping блокирует создание Draft.
API принимает Bearer, Basic и API key в header/query, если соответствующая Auth Profile принадлежит текущему workspace, параметры схемы совпадают и все связанные Secrets активны с доступной current version. Cookie API key, OAuth2, OpenID Connect, mutual TLS, неизвестные схемы и несовместимые AND-варианты отображаются как unsupported и требуют ручной конфигурации. Apply повторяет проверку профиля и Secret внутри registry transaction; отсутствующие, foreign, несовместимые профили и недоступные Secrets возвращают одну sanitized ошибку без metadata профиля.
Изменение требований безопасности после preview делает старый preview непригодным для применения: digest включает выбранные mapping-значения, а исходный документ повторно проверяется перед Apply. Literal credentials в поддерживаемых source locations отклоняются до сохранения upload или внешнего snapshot; ответ содержит только безопасный error code и не включает значение. Отдельный экран выбора Auth Profile в мастере относится к Story 2.11.
## Что создается
Для каждого выбранного метода 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-импорт не входят.