Document OpenAPI import workflow

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)

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.

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
 

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 и успешные ответы.
 
 Раздел **Использование** показывает количество вызовов, ошибки и задержки по операциям.
-