From 42dd796927818ce7a3ea6916a5d5b98c93d8de8f Mon Sep 17 00:00:00 2001 From: github-ops Date: Tue, 23 Jun 2026 21:03:35 +0000 Subject: [PATCH] Document OpenAPI import workflow --- docs/README.md | 1 + docs/openapi-import.md | 63 ++++++++++++++++++++++++++++++++++++++++++ docs/protocols/rest.md | 8 +++--- docs/ui.md | 29 ++++++++++++++++++- 4 files changed, 96 insertions(+), 5 deletions(-) create mode 100644 docs/openapi-import.md diff --git a/docs/README.md b/docs/README.md index fe7db1c..bbefc66 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,6 +16,7 @@ Crank превращает REST API endpoint-ы в MCP-инструменты, - [Веб-интерфейс](./ui.md) - [REST-инструменты](./protocols/rest.md) +- [Импорт OpenAPI](./openapi-import.md) - [Секреты и профили авторизации](./secrets-and-auth.md) - [Журналы и использование](./observability.md) - [Проектирование MCP-инструментов](./tool-design.md) diff --git a/docs/openapi-import.md b/docs/openapi-import.md new file mode 100644 index 0000000..62f9f34 --- /dev/null +++ b/docs/openapi-import.md @@ -0,0 +1,63 @@ +# Импорт OpenAPI + +Crank умеет импортировать REST API из OpenAPI 3.x и Swagger 2.0 документов. Импорт создает черновики MCP-инструментов, которые можно проверить и доработать в мастере операции перед публикацией. + +## Как импортировать + +1. Откройте раздел **Операции**. +2. Нажмите **Импорт OpenAPI** рядом с кнопкой **Новая операция**. +3. Загрузите `.yaml`, `.yml`, `.json` файл или вставьте текст спецификации. +4. Нажмите **Разобрать документ**. +5. Проверьте preview: для каждого метода показываются поля `Path`, `Query`, `Header`, `Body` и поля ответа. +6. Выберите нужные группы и методы. +7. Проверьте `Base URL`. Если в документе нет `servers`, укажите URL вручную. +8. Выберите поведение при конфликте имени: + - **Создать копию с новым именем** — Crank добавит суффикс `_2`, `_3` и так далее. + - **Пропустить** — существующие операции не будут изменены. +9. Нажмите **Создать черновики**. + +## Что создается + +Для каждого выбранного метода Crank создает отдельную операцию в статусе черновика: + +- имя инструмента берется из `operationId`, а если его нет — строится из HTTP-метода и пути; +- отображаемое имя берется из `summary`; +- описание инструмента берется из `description`; +- группа берется из первого `tag`; +- query/path/header параметры становятся входными параметрами MCP-инструмента; +- JSON `requestBody` с объектной схемой раскладывается в отдельные входные поля; +- схема успешного ответа берется из `200`, `201`, `202` или `default`. + +После импорта откройте созданный черновик в мастере операции. На шаге **Связи полей** Crank покажет уже созданный маппинг в визуальном виде: + +- `Path` — параметры из пути, например `/users/{id}`; +- `Query` — query-параметры URL; +- `Header` — заголовки запроса; +- `Body` — поля JSON-тела. + +YAML-маппинг остается доступен в блоке **Дополнительно**, но для обычной настройки его редактировать не нужно. + +## Рекомендации + +После разбора Crank показывает предупреждения, если в спецификации не хватает данных для качественного MCP-инструмента: + +- нет `operationId`; +- нет `summary` или `description`; +- нет схемы успешного ответа; +- нет `servers`; +- слишком много входных параметров; +- используется тело запроса без JSON-схемы. + +Эти предупреждения не блокируют импорт, но перед публикацией лучше открыть созданную операцию и проверить: + +- описание инструмента; +- входные поля и их обязательность; +- связи `Path / Query / Header / Body`; +- пример входных данных для теста; +- поля ответа, которые увидит MCP клиент. + +## Ограничения Community + +В Community импортируются только REST/HTTP методы: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. + +GraphQL, gRPC, WSDL, SOAP, WebSocket и streaming-протоколы не импортируются в Community. diff --git a/docs/protocols/rest.md b/docs/protocols/rest.md index 03b28b5..c2cbf43 100644 --- a/docs/protocols/rest.md +++ b/docs/protocols/rest.md @@ -55,11 +55,11 @@ REST operation в системе описывается следующими о 2. Выбирает HTTP method. 3. Указывает `path_template`. 4. При необходимости загружает пример входного и выходного `JSON`. -5. Система строит черновую схему и стартовый mapping. +5. Система строит черновую схему и стартовые связи полей. 6. Описывает или уточняет входные MCP-параметры. -7. Сопоставляет параметры с `path`, `query`, `headers` и `body`. +7. Сопоставляет параметры с `Path`, `Query`, `Header` и `Body` в визуальном конструкторе. 8. Указывает, откуда извлекать полезные данные в ответе. -9. При необходимости уточняет mapping через `JSONPath`. +9. При необходимости открывает блок **Дополнительно** и уточняет YAML/JSONPath вручную. 10. Запускает тест. 11. Публикует operation как MCP tool. @@ -80,7 +80,7 @@ Output mapping должен поддерживать: - извлечение вложенных полей - нормализацию отсутствующих значений -`JSONPath` является основным способом адресации конкретных параметров при работе со вложенными объектами и массивами. +В интерфейсе пользователь работает с таблицей связей. `JSONPath` остается внутренним форматом и расширенным режимом для сложных случаев. ## 7. Поведение runtime diff --git a/docs/ui.md b/docs/ui.md index df4bec6..759a66b 100644 --- a/docs/ui.md +++ b/docs/ui.md @@ -19,6 +19,34 @@ Черновик можно редактировать и тестировать. MCP-клиенты видят только опубликованные операции, которые привязаны к опубликованному агенту. +### Создание операции + +В мастере операции основной сценарий такой: + +1. Выбрать REST. +2. Выбрать upstream или добавить новый `Base URL`. +3. Указать HTTP-метод и путь endpoint-а. +4. Описать инструмент и его входную/выходную схему. +5. Загрузить или вставить JSON-пример запроса и ответа. +6. Связать поля инструмента с `Path`, `Query`, `Header` и `Body`. +7. Выбрать поля ответа API, которые вернет MCP-инструмент. +8. Запустить тест. +9. Сохранить и опубликовать операцию. + +Для обычной работы достаточно визуального конструктора связей. YAML/JSONPath открыт в блоке **Дополнительно** для сложных случаев: вложенные поля, ручная правка, перенос готовой конфигурации. + +Если пример ответа содержит массив, визуальное дерево показывает поля первого элемента как `items[0].name`. Это удобно, когда агенту нужно одно конкретное поле. Если агенту нужен весь список, используйте блок **Дополнительно** и верните массив целиком. + +### Импорт OpenAPI + +Кнопка **Импорт OpenAPI** создает черновики операций из OpenAPI/Swagger. После импорта откройте черновик в мастере и проверьте: + +- описание инструмента; +- входные поля; +- связи `Path / Query / Header / Body`; +- пример тестового запроса; +- поля ответа, которые попадут в результат инструмента. + ## Агенты Агент - это отдельный MCP endpoint с выбранным набором инструментов. @@ -51,4 +79,3 @@ API-ключ выдается на конкретного агента. Ключ Раздел **Логи** показывает вызовы операций, ошибки маппинга, ошибки REST API и успешные ответы. Раздел **Использование** показывает количество вызовов, ошибки и задержки по операциям. -