Документация

Встроенная документация формируется из карты роутов и отображается через рендер документации. На одной странице можно изучить операции, параметры и форматы ответов, а затем выполнить запрос к API.

Открытие документации

В административном разделе выберите «Сервисы → API-платформа → Документация». Пункт появляется, когда заполнен «Путь документации» и пользователю разрешён просмотр. Эту же страницу можно открыть по прямой ссылке и передать разработчику интеграции.

Для работы встроенного рендера в браузере должен быть включён JavaScript. Название, описание и адрес сервера задаются на вкладке «Документация» в настройках.

Просмотр роутов

Операции и параметры

Роуты сгруппированы по разделам. У каждой операции указаны HTTP-метод и путь относительно адреса API. Раскройте операцию, чтобы посмотреть описание, обязательные параметры, тело запроса и ответы. Состав этих сведений зависит от карты роутов: подробные описания и примеры добавляет разработчик.

Видимость по группам

На странице видны активные роуты из включённых наборов, разрешённые группам текущего пользователя сайта. Доступ к странице и видимость операций — отдельные проверки: схема прав.

Кнопка Authorize задаёт авторизацию API-запроса и не меняет видимый список операций.

Выполнение запроса

Подготовка

1. Проверьте адрес API в блоке Servers: запрос будет отправлен на этот сервер.
2. Откройте нужную операцию и нажмите Try it out.
3. Заполните обязательные параметры и тело запроса, если они предусмотрены.
4. Если роут требует авторизацию, нажмите Authorize и укажите данные для соответствующей схемы.
5. Нажмите Execute и изучите фактический HTTP-статус, тело и заголовки ответа.

Это реальные обращения к API. Операции создания, изменения и удаления выполняют действия на выбранном сервере.

Авторизация

Для Basic укажите логин и пароль пользователя. Для Bearer вставьте только значение токена: рендер добавит префикс Bearer в заголовок Authorization самостоятельно.

Тип токена зависит от операции: для прикладных запросов обычно используется access-токен, для обновления пары — refresh-токен. После ротации замените прежнее значение в Authorize. Порядок выпуска и обновления описан в разделе «Токены».

Вход в административный раздел не заменяет Basic- или Bearer-авторизацию API. При выполнении запроса продолжают действовать ограничения роута и настройки безопасности.

Первая проверка

После включения сервисных роутов откройте GET /up, нажмите Try it out, затем Execute. В штатной карте этот роут не требует токена. При разрешённом доступе ожидается HTTP 200 и JSON-ответ со сведениями о выполненном запросе: методе, контроллере, действии и параметрах.

Остальные сервисные операции проверяйте таким же способом, учитывая их параметры и ограничения. После проверки отключите сервисные роуты, если они больше не нужны, для дополнительной безопасности.

Обновление и оформление

Изменения карты роутов

После редактирования файла карты очистите кеш кнопкой «Очистить кеш» в настройках модуля и обновите страницу документации. При сохранении изменённых настроек модуль очищает кеш автоматически.

Если операция не появилась, проверьте её активность, включение соответствующего набора роутов и разрешения групп. Отсутствие операций может означать, что текущему пользователю нечего показывать.

Собственный интерфейс

Способ замены интерфейса описан в разделе «Рендер документации».