| Шаг 1: объект openapi | --> | Шаг 2: объект info | --> | Шаг 3: объект servers | --> | Шаг 4: объект paths | --> | Шаг 5: объект components | --> | Шаг 6: объект security | --> | Шаг 7: объект tags | --> | Шаг 8: объект externalDocs |
В объекте servers указывается базовый путь, используемый в ваших запросах API. Базовый путь - это часть URL, которая находится перед конечной точкой.
Пример объекта servers
servers:
- url: https://api.openweathermap.org/data/2.5/
Каждая из конечных точек (называемых в спецификации paths) будет добавляться к URL-адресу сервера, при отправке пользователями пробных запросов Try it out. Например, если одним из путей является /weather, то при отправке запроса Swagger UI представит путь к {server URL}{path} или https://api.openweathermap.org/data/2.5/weather.
Объект servers обладает гибкой настройкой. Можно указать несколько URL-адресов серверов, которые могут относиться к различным средам (тестовая, бета-версия, рабочая версия). При наличии нескольких URL-адресов серверов, пользователи могут выбирать среду в раскрывающемся списке серверов. Можно указать несколько URL-адресов серверов, например:
servers:
- url: https://api.openweathermap.org/data/2.5/
description: Production server
- url: http://beta.api.openweathermap.org/data/2.5/
description: Beta server
- url: http://some-other.api.openweathermap.org/data/2.5/
description: Some other server
В Swagger UI выбор из нескольких серверов осуществляется при помощи выпадающего списка
Если указан один сервер все равно будет отображаться выпадающий список, но с одним вариантом.
В URL-адрес сервера также можно включать переменные, которые будут заполняться сервером во время выполнения. Кроме того, если для разных путей (конечных точек) требуются разные URL-адреса сервера, можно добавить объект servers в качестве свойства в объекте операции объекта path. URL-адрес локально объявленных серверов переопределяет URL-адрес глобальных серверов.
См. Overriding Servers в разделе «Сервер API и базовый URL» (документы Swagger) для получения дополнительной информации.
Вставим объект servers (первый пример кода выше, показывающий только один URL) в редактор Swagger, добавив к имеющемуся коду. Swagger UI будет выглядеть следующим образом:
