Document OpenAPI import workflow

2026-06-23 21:03:35 +00:00
parent 04f63e690c
commit 42dd796927
4 changed files with 96 additions and 5 deletions
@@ -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)
@@ -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.
@@ -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
@@ -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 и успешные ответы.
 Раздел **Использование** показывает количество вызовов, ошибки и задержки по операциям.