Сохранение запросов и примеры протоколов
Powerduck разделяет тестируемый запрос и публикуемый API-контракт.
| Действие | Результат |
|---|---|
| Сохранить в строке URL | Сохраняет локальные настройки отладки этого запроса, не изменяя документ OpenAPI. |
| Быстрый запрос: сохранить в спецификацию | Добавляет операцию в выбранные документ и папку. |
| Запрос спецификации: обновить спецификацию | Перед обновлением контракта показывает целевые метод и путь, а также предпросмотр определения. |
| Сохранить документ / Cmd+S или Ctrl+S | Записывает текущий документ OpenAPI на диск. На вкладке быстрого запроса сочетание сохраняет этот быстрый запрос. |
Локальный запрос содержит выбранный сервер, URL, метод, значения параметров, тело, скрипты и настройки транспорта. Черновики запросов спецификации во время редактирования остаются в памяти; кнопка сохранения в строке URL сохраняет их в хранилище процесса рендеринга приложения с префиксом powerduck.debug.v1:. Записи разделены по ID документа, пути и методу. Очистка данных браузера или приложения удаляет это локальное состояние; экспорт OAS его не включает. Это хранилище не является зашифрованным хранилищем секретов: используйте ссылки на окружение вместо открытых учётных данных в URL, заголовках или телах. Элементы аутентификации используют отдельный механизм сохранения учётных данных.
x-powerduck-request не является официальным расширением контракта. Добавление в спецификацию и её обновление не создают это поле. Оно не должно описывать метод, параметр, тело запроса или ответ. Простое открытие документа не переписывает существующие копии в других операциях.
Явное обновление определения
Обновление спецификации показывает целевые метод и путь и сохраняет существующие ответы и схемы. Определения параметров включаются только по выбору; отладочные значения не копируются. JSON-тело добавляется как пример только при явном выборе. Типичные имена полей учётных данных исключаются, но проверяйте произвольный текст и примеры перед публикацией. Скрипты и переопределения аутентификации не относятся к полям контракта.
Изменение метода или пути не позволяет перезаписать уже существующую целевую операцию. Локальные ссылки на операции перенаправляются. Пользовательский метод, например PURGE, хранится в paths./cache.additionalOperations.PURGE и требует OpenAPI 3.2. Предпросмотр сообщает об этом требовании; применение обновления устанавливает версию документа 3.2.0. Проверьте также поддержку этой версии инструментами, которые будут использовать документ.
Схемы протоколов по-прежнему доступны для изменения через редактирование документации. Э то явно меняет определение; отправка или сохранение отладочного запроса не переписывает схемы незаметно.
Официальные примеры для скачивания
Это поддерживаемые примеры определений, а не публичные API-сервисы Powerduck. Все эндпоинты указывают на локальные сервисы, которые вы предоставляете самостоятельно. Импорт файла не запускает сервисы, не подключается автоматически и не выдаёт учётные данные.
- Все протоколы
- HTTP и пользовательский PURGE
- SSE
- WebSocket
- GraphQL
- gRPC и echo.proto
- MCP Streamable HTTP
- A2A 1.0 JSON-RPC
Для gRPC скачайте echo.proto рядом с YAML-файлом и при необходимости выберите его фактический локальный путь в клиенте. Сервер должен реализовать powerduck.examples.Echo/Echo на порту 50051. Остальные примеры тоже требуют соответствующего сервера; это не демонстрации проверки работающего бэкенда.
Справочник расширений контракта
У каждой операции есть обычный метод OAS, operationId, summary и responses. Привязки не-HTTP используют операцию OAS как точку привязки документации; post в примере gRPC не означает преобразование gRPC в REST-эндпоинт.
| Расширение | Назначение и поля в примерах |
|---|---|
x-protocol | sse, websocket, graphql, grpc, mcp или a2a. Для HTTP можно не указывать. |
x-session | Объявляет долгоживущую сессию протокола; в примерах используется для WebSocket и MCP. |
x-websocket | url, необязательные subprotocols, headers и messages. У каждого описанного сообщения есть id, name, type, body, requestSchema, responseSchema. Не помещайте учётные данные в заголовки. |
x-graphql | endpoint, query, operationName, variablesSchema, публичные variables, responseSchema. |
x-grpc | address, service, method, kind, reflection, protoPaths, includeDirs и описанные messages. kind поддерживает unary/server_streaming/client_streaming/bidi_streaming. Локальные пути proto зависят от развёртывания. |
x-mcp | transport, endpoint, method и специфичные для метода поля name, argumentsSchema, публичные arguments, responseSchema. Операции с ресурсами используют uri; не смешивайте поля несвязанных методов. |
x-a2a | Явные version, binding, endpoint, method, requestSchema, responseSchema и публичный example. Форматы данных 0.3 и 1.0 различаются; см. A2A. |
x-response-stream | Необязательное указание намерения использовать потоковый GraphQL, если фактические сервер и транспорт это поддерживают. Для обычных запросов GraphQL не требуется. |
SSE описывает данные каждого события стандартным полем responses.200.content.text/event-stream.itemSchema. HTTP использует стандартные параметры, requestBody, responses и схемы безопасности. Не придумывайте блок конфигурации x-sse и не храните отладочное состояние в расширении контракта.
Примеры содержат полные рабочие конфигурации выбранной привязки, а не все взаимоисключающие варианты. MCP stdio требует отдельно настроенной локальной программы; скачиваемые примеры намеренно не запускают её автоматически.
Интеграция пакетов
Настольный интерфейс отвечает за сохранение локального состояния отладки и явную запись спецификации. @powerduck/openapi-parser уже читает пользовательские методы через additionalOperations; @powerduck/tree и @powerduck/oas-document используют эту структуру контракта. @powerduck/openapi-request получает аргументы выполнения отдельно от спецификации. Для выполнения запросов x-powerduck-request не требуется.
Разделение сохранения не добавляет новых публичных параметров npm. Используйте существующие расширения протоколов для данных контракта, а текущие отладочные значения передавайте API выполнения запросов. Не привязывайте экспортёры, генераторы и инструменты MCP к приватной структуре состояния запросов.