Сервисы и производительность тема 23 из 27

Swagger

Доступ к swagger документации можно получить по адресу {домен}/api/doc

в этой теме 2
  1. Контроллер
  2. Документация не обновляется

Описание API в JSON — {домен}/api/doc/json (публичного файла /upload/swagger.json больше нет). Настройки модуля → «Основное» → «Документация API и журнал»: «Открыта всем» (по умолчанию) или «Только администраторам» — на рабочем сайте выберите второе, остальным оба адреса отвечают 404.

Swagger

Контроллер

Чтобы более подробно описать эндпойнты для swagger, нужно использовать методы:

  • methodDocMap - описание эндпоинтов, задается название и описание
  • parametersDocMap - описание параметров конкретного эндпоинта

Разберем более подробно.

  1. Метод methodDocMap.

Чтобы описать конкретные методы контроллера, нужно переопределить метод methodDocMap из класса AbstractController. Этот метод должен вернуть массив.

Параметры:

  • summary - название эндпойнта
  • description - описание эндпойнта
  • access - доступ: guest, auth (гость получает 401 «Требуется авторизация», в Swagger это показано) или admin
  • settingsTab - код вкладки настроек модуля, ссылка на неё выводится в описании
  • errors - ошибки метода: [[код, текст, когда]], выводятся ответами 4xx
  • guide - код темы руководства (/api/doc/guide), ссылка «Руководство»
  • exampleResponse - пример ответа 200 (массив или замыкание от инфоблока)
php
class CustomController extends AbstractController
{

    /*
     * Описание эндпоинтов для Swagger
     *
     * Данный метод может быть переопределён из класса AbstractController
     */
    protected static function methodDocMap (): array
    {
        return [
            'post_cancel_order' => [
                'summary' => 'Отмена заказа',
                'description' => 'Отмена заказа по ID для текущего пользователя',
            ],
            'get_order' => [
                'summary' => 'Получение заказа',
                'description' => 'Получение заказа по ID для текущего пользователя'
            ],
        ];
    }
  1. Метод parametersDocMap. Чтобы описать параметры метода контроллера, нужно переопределить метод parametersDocMap из класса AbstractController. Этот метод должен вернуть массив.

Параметры:

  • description - описание параметра конкретного эндпойнта
php
    /*
     * Описание параметров конкретного эндпоинта для Swagger
     *
     * Данный метод может быть переопределён из класса AbstractController
     */
    protected static function parametersDocMap ()
    {
        return [
            'post_cancel_order' => [
                "orderID" => [
                    'description' => 'ID заказа'
                ],
            ],
            'get_order' => [
                "orderID" => [
                    'description' => 'ID заказа'
                ],
            ]
        ]; 
    }

Документация не обновляется

Если документация не обновляется, можно попробовать следующие действия:

  1. Сочетание клавиш Ctrl + F5 для полного обновления страницы в браузере, игнорируя кэш.
  2. Сбросить кэш в Bitrix, для этого перейдете в Админ.панель -> Настройки -> Настройки продукта -> Автокеширование -> Очистка файлов кеша

Подключим BIK.REST-API к вашему сайту

Оставьте заявку — установим и настроим модуль, ответим на вопросы по API.

c заботой о вас, мы используем cookie на своем сайте, чтобы интернет был чистым и прекрасным