Описание API в JSON — {домен}/api/doc/json (публичного файла /upload/swagger.json больше нет). Настройки модуля → «Основное» → «Документация API и журнал»: «Открыта всем» (по умолчанию) или «Только администраторам» — на рабочем сайте выберите второе, остальным оба адреса отвечают 404.
Контроллер
Чтобы более подробно описать эндпойнты для swagger, нужно использовать методы:
- methodDocMap - описание эндпоинтов, задается название и описание
- parametersDocMap - описание параметров конкретного эндпоинта
Разберем более подробно.
- Метод methodDocMap.
Чтобы описать конкретные методы контроллера, нужно переопределить метод methodDocMap из класса AbstractController. Этот метод должен вернуть массив.
Параметры:
- summary - название эндпойнта
- description - описание эндпойнта
- access - доступ:
guest,auth(гость получает 401 «Требуется авторизация», в Swagger это показано) илиadmin - settingsTab - код вкладки настроек модуля, ссылка на неё выводится в описании
- errors - ошибки метода:
[[код, текст, когда]], выводятся ответами 4xx - guide - код темы руководства (
/api/doc/guide), ссылка «Руководство» - exampleResponse - пример ответа 200 (массив или замыкание от инфоблока)
class CustomController extends AbstractController
{
/*
* Описание эндпоинтов для Swagger
*
* Данный метод может быть переопределён из класса AbstractController
*/
protected static function methodDocMap (): array
{
return [
'post_cancel_order' => [
'summary' => 'Отмена заказа',
'description' => 'Отмена заказа по ID для текущего пользователя',
],
'get_order' => [
'summary' => 'Получение заказа',
'description' => 'Получение заказа по ID для текущего пользователя'
],
];
} - Метод parametersDocMap. Чтобы описать параметры метода контроллера, нужно переопределить метод parametersDocMap из класса AbstractController. Этот метод должен вернуть массив.
Параметры:
- description - описание параметра конкретного эндпойнта
/*
* Описание параметров конкретного эндпоинта для Swagger
*
* Данный метод может быть переопределён из класса AbstractController
*/
protected static function parametersDocMap ()
{
return [
'post_cancel_order' => [
"orderID" => [
'description' => 'ID заказа'
],
],
'get_order' => [
"orderID" => [
'description' => 'ID заказа'
],
]
];
} Документация не обновляется
Если документация не обновляется, можно попробовать следующие действия:
- Сочетание клавиш Ctrl + F5 для полного обновления страницы в браузере, игнорируя кэш.
- Сбросить кэш в Bitrix, для этого перейдете в Админ.панель -> Настройки -> Настройки продукта -> Автокеширование -> Очистка файлов кеша