Files
crank/docs/openapi-import.md
T

11 KiB
Raw Blame History

Импорт 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.

Новые imports используют normalized-ir-v4 / preview-v4. Сохранённые v2/v3 jobs воспроизводят сохранённый preview, а legacy-v1 использует отдельную историческую projection. Обновление importer не меняет inputs существующих jobs.

Другие форматы спецификаций и протоколов в Community-импорт не входят.