Files
crank/docs/openapi-import.md
T

18 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, варианты успешного ответа и effective security requirements.
  6. Выберите нужные группы и методы.
  7. Проверьте Base URL. Если в документе нет servers, укажите URL вручную.
  8. Для уже существующей операции подтвердите решение отдельно: пропустить точную операцию, создать отдельную операцию с указанным вами свободным именем или добавить новую черновую версию к выбранной REST-операции. Автоматический подбор имени при применении плана не выполняется.
  9. Создайте план и проверьте число выбранных, исключённых, доступных и заблокированных методов. По умолчанию полный план требует, чтобы каждый метод можно было применить; для частичного импорта явно оставьте только нужные методы.
  10. Для защищённых методов задайте совместимый Auth Profile через import API, выбрав конкретную security alternative из вариантов preview. Незакрытое обязательное требование оставляет метод заблокированным; выбор этих привязок в UI пока недоступен.
  11. Подтвердите план и примените его. Создание плана не меняет операции. Применение выполняет все выбранные изменения одной транзакцией и показывает результат для каждого метода.

Загрузка и восстановление

Браузер отправляет выбранный файл как multipart/form-data; границу multipart формирует сам браузер. Файл остаётся только в памяти текущего окна импорта. При замене файла, сбросе, закрытии окна, смене workspace/языка или уходе со страницы текущий запрос отменяется, а поздний ответ игнорируется. При pagehide (включая BFCache) выбранный файл и Base URL очищаются: после возврата нужно выбрать файл заново, повтор старой загрузки не предлагается.

До сохранения source snapshot импорт проверяет основной документ и загруженные allowlisted $ref-документы вместе, включая разрешённые ссылки. Если такая проверка находит literal credential, загрузка отклоняется; значение не попадает в artifact storage, preview или текст ошибки. Безопасные внешние ссылки сохраняются как digest-проверенные immutable snapshots и не загружаются заново при Apply.

Для ошибки можно выбрать файл заново или нажать Повторить. Диагностика загрузки показывает только ограниченные имя/размер файла и, если 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-v5 / preview-v5. Исторические v2/v3/v4 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 schemes Поддерживается Поддерживается для basic и API key header/query Схемы типизируются без credential values; preview предлагает только совместимые workspace Auth Profiles с активными current secrets
Security requirements с несколькими alternatives Поддерживается Поддерживается Каждая OR alternative сохраняется отдельно и получает собственный список совместимых Auth Profiles; unsupported alternative не блокирует доступную соседнюю alternative
Несколько schemes в одной security alternative (AND) Blocker для этой alternative Blocker для этой alternative Составное требование сохраняет имена схем в finding; оно не становится actionable через single-scheme Auth Profile
OAuth2, OpenID Connect, mutual TLS и неизвестные схемы Manual configuration Manual configuration Явный unsupported finding; схема не извлекает token/client secret и не становится actionable автоматически
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.