Question

在OpenAPI 3.0 Specification中，根OpenAPI Object具有servers属性，该属性是Server Objects的数组。 Path Item Object还允许使用可选的servers属性。

规范中给出的描述并没有清楚说明servers如何有所帮助。

servers财产有什么意义？我们是否有任何示例将servers的用例解释为根OpenAPI对象的直接属性以及路径项的属性？

Answer 1

servers指定API的一个或多个目标服务器，换句话说，API调用的基本URL。端点路径（例如/users/{id}）是相对于这些服务器定义的。一些API具有单个目标服务器;其他人可能会提供多个服沙箱与生产或不同地理区域的区域服务器（例如：AWS）。

默认情况下，OpenAPI定义中的所有操作都使用全局定义的servers，但也可以为特定路径和操作覆盖servers。这对于某些操作使用与其余操作不同的服务器的API非常有用。这样，您可以在单个API定义中记录所有操作，而不是将其拆分为多个定义，每个服务器一个。

示例： Dropbox API

大多数端点位于api.dropboxapi.com域。
内容上传/下载端点位于content.dropboxapi.com。
Longpoll端点位于notify.dropboxapi.com。
OAuth端点位于www.dropbox.com。

Dropbox API定义可能如下所示：

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 Host and Base Path指南。

OpenAPI 3.0中服务器属性的意义是什么？

1 个答案: