Какое значение имеет свойство серверов в OpenAPI 3.0? - PullRequest
Новая
       7

Какое значение имеет свойство серверов в OpenAPI 3.0?

0 голосов
/ 26 мая 2018

В спецификации OpenAPI 3.0 корневой объект OpenAPI имеет свойство servers, представляющее собой массив объектов сервера .И Объект Path Path также допускает необязательное свойство servers.

Описание, данное в Спецификации, не дает четкого представления о том, как servers может быть полезным.

Какое значение свойства servers?Есть ли у нас какой-либо пример, который объясняет варианты использования servers как прямое свойство корневого объекта OpenAPI, а также как свойство элемента пути?

1 Ответ

0 голосов
/ 26 мая 2018

servers указывает один или несколько целевых серверов для API, другими словами, базовый URL-адрес для вызовов API.Пути к конечным точкам (например, /users/{id}) определяются относительно этих серверов.Некоторые API имеют один целевой сервер;другие могут предлагать несколько серверов, например «песочница против производства», или региональные серверы для различных географических областей (например, AWS).

По умолчанию все операции в определении OpenAPI используют глобально определенный servers, но servers также может быть переопределено для определенных путей и операций.Это полезно для API, где некоторые операции используют сервер, отличный от остальных операций.Таким образом, вы можете документировать все операции в одном определении API, а не разбивать его на несколько определений, по одному на сервер.

Пример: API Dropbox

  • Большинство конечных точек находятся в домене api.dropboxapi.com.
  • Конечные точки загрузки / выгрузки контента находятся на content.dropboxapi.com.
  • Конечная точка Longpoll включена notify.dropboxapi.com.
  • Конечные точки OAuth включены www.dropbox.com.

Определение API Dropbox может выглядеть следующим образом: 

openapi: 3.0.0
info:
  title: Dropbox API
  version: 1.0.0

servers:
  - url: 'https://api.dropboxapi.com/2'

paths:
  # These endpoints are on api.dropboxapi.com (use global `servers`)
  /file_requests/list:
    ...
  /users/get_account:
    ...

  /files/upload:
    # File upload/download uses another target server
    servers:
      - url: 'https://content.dropboxapi.com/2'
    ...

  /files/list_folder/longpoll:
    # Longpolling uses another target server
    servers:
      - url: 'https://notify.dropboxapi.com/2'
    ...

Для получения дополнительной информации и примеров ознакомьтесь с руководством по API-хосту и базовому пути .

...