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

Рендер документации — интерфейс, который отображает описание API: роуты, параметры и ответы.

По умолчанию

Компонент native.api:docs использует Swagger UI для просмотра документации, авторизации и выполнения запросов.

// Подключение стандартного рендера в сервисе документации
$APPLICATION->IncludeComponent(
    'native.api:docs',
    '.default',
    [],
    false
);

Порядок работы с интерфейсом — в разделе «Документация».

Описание API

Компонент формирует описание OpenAPI 3.0.3 из карты роутов. В него попадают активные роуты, доступные группам пользователя, открывшего документацию.

Проверка права чтения документации
      ↓
Карта включённых наборов роутов
      ↓
Отбор активных роутов по группам посетителя
      ↓
Описание OpenAPI в $arResult['SCHEMA']
      ↓
Шаблон компонента
├─ Стандартный → Swagger UI
└─ Собственный → ваш интерфейс

Сформированное описание кешируется с учётом групп посетителя. Право открыть страницу проверяется и при чтении из кеша.

Swagger UI отображает готовое описание. Состав документации и проверки API определяет модуль.

Собственный рендер

Скопируйте компонент в /local/components/native.api/docs/ и измените его стандартный шаблон, чтобы использовать свой интерфейс вместо Swagger UI.

Описание передаётся в шаблон как JSON в $arResult['SCHEMA'].

Пример шаблона

Минимальный вывод списка роутов в файле templates/.default/template.php скопированного компонента:

<?php

use Bitrix\Main\Web\Json;

if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) {
    die();
}

$schema = Json::decode($arResult['SCHEMA']);
?>

<ul>
    <?php foreach ($schema['paths'] as $path => $operations): ?>
        <?php foreach ($operations as $method => $operation): ?>
            <li><?= htmlspecialcharsbx(strtoupper($method) . ' ' . $path) ?></li>
        <?php endforeach; ?>
    <?php endforeach; ?>
</ul>

При замене шаблона сохраните класс компонента: он проверяет доступ и отбирает роуты по группам.