服务器属性在 OpenAPI 3.0 中有什么意义？

Question

在OpenAPI 3.0 规范中，根OpenAPI 对象具有作为服务器对象servers数组的属性。并且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。
• 长轮询端点已打开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 主机和基本路径指南以获取更多详细信息和示例。