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

Question

在OpenAPI 3.0 Specification, the root OpenAPI Object has the servers property which is an array of Server Objects. And the Path Item Object中也允许可选servers属性.

规范中给出的描述并未明确说明 servers 有何帮助。

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

Answer 1

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

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

示例： Dropbox API

大多数端点都在 api.dropboxapi.com 域中。
内容 upload/download 端点在 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 中的意义是什么？

What is the significance of servers property in OpenAPI 3.0?

openapi

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