.. _Integration_Common_OpenApiAndSwagger:

Поддержка OpenAPI и Swagger
###########################

API Продукта поддерживает спецификацию `OpenAPI <https://swagger.io/resources/open-api/>`_. 
Для генерации метаданных OpenAPI используется `Swagger <https://swagger.io/>`_.
Для облегчения разработки, тестирования и внедрения используется `SwaggerUI <https://swagger.io/tools/swagger-ui/>`_.

SwaggerUI
*********

Для доступа к странице SwaggerUI в браузере нужно указать URL одного из развернутых HTTP-сервисов Продукта, 
после чего браузер автоматически будет перенаправлен на страницу SwaggerUI.
Эта страница содержит подробное описание всех доступных запросов к API и структур данных.
Здесь же можно загрузить JSON-файл с метаданными OpenAPI.

.. image:: img/OpenApiAndSwagger-1.png
   :scale: 43
   :align: center
   :alt: SwaggerUIPage

Аутентификация и авторизация в SwaggerUI
****************************************

Выполнение запросов в SwaggerUI требует аутентификации и авторизации пользователя.
Нужно зайти в раздел ``Авторизация, пользователи и роли``, открыть POST-запрос ``token`` ("Получить токен"), нажать ``Try it out``:

   .. image:: img/OpenApiAndSwagger-2.png
      :scale: 41
      :align: center
      :alt: TokenTryItOut

Затем в поле ``Request body`` указать логин и пароль пользователя (см. :ref:`Integration_Common_Authentication_DefaultAccounts`) и нажать ``Execute``:

   .. image:: img/OpenApiAndSwagger-3.png
      :scale: 41
      :align: center
      :alt: TokenExecute

Затем скопировать токен из ответа:

   .. image:: img/OpenApiAndSwagger-4.png
      :scale: 41
      :align: center
      :alt: CopyTokenFromReposne

Затем наверху страницы нажать ``Authorize``:

   .. image:: img/OpenApiAndSwagger-5.png
      :scale: 70
      :align: center
      :alt: AuthorizeButton

Затем в открывшейся форме вставить скопированный токен в поле ``Value`` и нажать ``Authorize``, после нажать ``Close``:

   .. image:: img/OpenApiAndSwagger-6.png
      :scale: 70
      :align: center
      :alt: AuthorizeForm

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

Для выполнения запросов в SwaggerUI нужно найти требуемый раздел в списке либо с помощью поиска.
Затем зайти в раздел, открыть требуемый запрос в разделе, нажать ``Try it out``:

   .. image:: img/OpenApiAndSwagger-7.png
      :scale: 41
      :align: center
      :alt: RequestTryItOut

Затем задать параметры запроса в списке ``Parameters`` и/или тело запроса в поле ``Request body`` и нажать ``Execute``:

   .. image:: img/OpenApiAndSwagger-8.png
      :scale: 41
      :align: center
      :alt: RequestExecute

Ответ сервера будет доступен в поле ``Server response``:

   .. image:: img/OpenApiAndSwagger-9.png
      :scale: 41
      :align: center
      :alt: ServerResponse