Files
crank/docs/openapi-import.md
T

16 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. Для уже существующей операции подтвердите решение отдельно: пропустить точную операцию, создать отдельную операцию с указанным вами свободным именем или добавить новую черновую версию к выбранной 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.

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

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

Нормативная матрица и regression corpus

Машинная матрица версии 1.0.2 хранится в crates/crank-import/tests/support-matrix.yaml; corpus version — 1.0.3. Матрица фиксирует контракт отдельно для OpenAPI 3.0, OpenAPI 3.1 и Swagger 2.0. Acceptance test запускает нормализатор на отдельном probe для каждой строки, включая все 100 успешных кодов в каждом формате, и сверяет сохранённую semantics или точный blocker; выполненные probes списываются со всех строк версии, поэтому неподвергнутая проверкой строка матрицы падает gate. Версия corpus 1.0.3 добавляет hostile fixture hostile-security-scope.json: document-level требование безопасности блокирует только унаследовавшего его secured candidate (GET /secure, location /security/0), а операция с явным security: [] (GET /public) остаётся actionable без глобального blocker; oversized hostile JSON остаётся тем же canonical JSON с ожидаемым parser rejection.

Конструкция OpenAPI 3.0/3.1 Swagger 2.0 Сохраняемый контракт или finding
GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS Поддерживается Поддерживается Метод и исходный path переходят в Operation
path, query, header, cookie параметры Поддерживается path, query, header поддерживаются; cookie явно unsupported Имя, schema, required и source location сохраняются; Swagger cookie получает unsupported_cookie_parameter
JSON, urlencoded, multipart Поддерживается Поддерживается по consumes/body parameter Schema и content type остаются частью request contract
Успешные 2xx, включая 204 Поддерживается Поддерживается Каждая строка 200–299 проверяется отдельным probe; status сохраняется, а 204/205 остаются bodyless
Локальные и allowlisted external $ref Поддерживается Поддерживается Разрешение только из загруженного документа или digest-проверенного snapshot; тесты не загружают fixture по сети
allOf, oneOf, anyOf Поддерживается Поддерживается Совместимые allOf ветви объединяются; oneOf и anyOf остаются вариантами schema
bearer/basic/API key security requirements Blocker до выбора Auth Profile Blocker до выбора Auth Profile unsupported_security_requirement; requirement вычисляется per-operation с наследованием document-уровня; credentials не импортируются и не попадают в preview
security override: operation-level security: [] Поддерживается Поддерживается Явный пустой массив отключает наследование: только operations с эффективным requirement получают source-located blocker, связанные операции остаются actionable
Микс public/secured operations Поддерживается Подвергается проверке Blocker принадлежит только затронутому candidate; global blocker не создаётся для требований одного operation
XML, TRACE, CONNECT Unsupported Unsupported Source-located finding; blocker не становится actionable Draft

Offline corpus в crates/crank-import/tests/corpus/ содержит 50 synthetic representative документов и hostile subset. Manifest фиксирует SHA-256 исходных файлов, canonical digest JSON, происхождение и лицензию; для representative документов он также фиксирует полный canonical preview и frozen candidates (schemas, mappings, actionable/blocker), а для hostile — ожидаемые отказы и findings. Команда just openapi-corpus прогоняет настоящий normalizer, сравнивает независимо перечисленные raw source pointers с canonical source tree и coverage ledger, проверяет порог 95% actionable от всех representative Operations и отдельно нулевой silent loss. Evidence связывает digest manifest и matrix, включает content digest и создаётся без перезаписи; конфликт содержимого для того же identity останавливает gate. CI прикладывает crates/crank-import/target/openapi-corpus/evidence-<identity>.json. Artifact не содержит загруженный исходник или значения secret-like examples.