Пробные запросы

Отправьте настоящий запрос из браузера прямо со страницы эндпоинта, с поддержкой авторизации и с прокси на том же origin, чтобы не упереться в CORS.

Использование

У панели запроса каждого эндпоинта рядом с вкладками языков есть переключатель режима Code / Try it out. Try it out — это редактируемая форма (базовый URL, параметры пути, строки запроса и заголовков, тело запроса), которая через executeRequest() отправляет настоящий запрос и показывает результат на вкладке Live рядом с объявленными примерами ответов (JSON выводится с отступами, а при сетевой ошибке или проблеме с CORS появляется понятное сообщение вместо сырой ошибки). Базовый URL по умолчанию берётся из первой записи массива servers[] в документе OpenAPI, если она есть, и всегда доступен для правки.

Авторизация

У эндпоинтов с требованием security появляется встроенная форма авторизации, по одному полю на каждую объявленную схему:

  • apiKey: уходит в заголовок или параметр запроса, в зависимости от объявленного места.
  • http bearer, OAuth2 и OpenID Connect: все принимают токен, который вы вставляете напрямую, никакой поток OAuth не выполняется.
  • http basic: ожидает user:pass.

Учётные данные глобальные (общие для всех эндпоинтов с этой схемой, как и настоящий токен разработчика) и сохраняются в localStorage, так что переживают перезагрузку.

Когда в успешном ответе на вкладке Live встречается поле, похожее на токен (например, access_token у эндпоинта логина, в том числе вложенный в обёртку вроде data.access_token), кнопка «Использовать как токен …» подставит его как учётные данные на остаток сессии. Копировать вручную не придётся.

Прокси на том же origin

По умолчанию Try it out — это прямой fetch() из браузера в целевой API, подчиняющийся его политике CORS. Если DocfyUiModule.setup() из nestjs-docfy (см. справочник API) настроен с документом OpenAPI, docfy-ui замечает подставленную глобальную переменную window.__DOCFY_PROXY_PATH__ и отправляет запрос через серверный прокси на том же origin, поэтому CORS вообще не применяется.

Белый список прокси строится только из абсолютных URL в массиве servers[] документа. Неявного запасного варианта «тот же origin, что и у запроса» нет, потому что он зависел бы от заголовков, которыми управляет клиент. Запрос к запрещённому origin, как и любой другой сбой на самом прокси, возвращается с заголовком X-Docfy-Proxy-Error, чтобы docfy-ui отличал падение прокси от настоящего ответа вашего API.