API 服务器

此页面显示如何指定可以访问 API 的服务器，其中可以包含多个 URL 甚至可变部分。

服务器对象

该服务器对象提供 API 所提供的基本 URL。它可以在根目录的 servers 数组中找到 OpenAPI 对象、该路径项对象和该操作对象.

用星号标记的边缘是数组。
OpenAPI 对象在 OpenAPI 描述的结构页面中解释。
路径、路径项和操作对象在 API 端点页面中解释。

在 servers 数组中的每个元素都是一个服务器对象，至少提供一个 url 字段，其中包含该服务器的基本 URL。可选的 description 有助于保持服务器列表的组织

servers:
- url: https://europe.server.com/v1
  description: Server located in Germany.
- url: https://america.server.com/v1
  description: Server located in Atlanta, GA.
- url: https://asia.server.com/v1
  description: Server located in Shenzhen

然后将各个 API 端点（如路径对象中所指定）追加到此 URL，以构造完整的端点 URL。例如

servers:
- url: https://server.com/v1
paths:
  /users:
    get:

可以通过在 URL https://server.com/v1/users 上执行 GET 请求来访问上述操作。

当为给定操作在不同级别指定多个 servers 数组时，只考虑最内层的数组。例如，在这种情况下

servers:
- url: https://server1.com
paths:
  /users:
    get:
      servers:
      - url: https://server2.com

对 /users 端点的 GET 请求将从 https://server2.com 而不是从 https://server1.com 提供服务。

注意：在 OpenAPI 描述 (OAD) 中提供多个服务器时，请记住它们都应该提供相同的 API（因为它们在同一个 API 描述中列出）。

如果服务器用于不同的环境（例如测试和生产），它们的 API 可能会不同，在单个 OAD 中描述它们将很复杂。

在这些情况下，最好使用不同的 OAD 甚至不同的 API 版本。阅读重复使用描述页面以了解如何在这些情况下避免代码重复和维护成本。

相反，如果未提供服务器，则假定所有 API 端点相对于提供 OpenAPI 描述文档的位置。请注意，如果您的 OAD 分散在多个文档中，则每个端点 ID 假定相对于其描述所在的文档。描述服务器可确保您的端点相同，无论您的 OAD 如何组织。

最后，服务器 URL 可以包含可变部分，如下所示。

服务器变量

服务器 URL 可以包含变量，用大括号 {} 分隔

servers:
- url: https://{username}.server.com:{port}/{version}

这些变量必须在 variables 字段中进一步详细说明。此字段是将变量名（与服务器 url 中的大括号中的变量名匹配）与服务器变量对象配对的映射。

该服务器变量对象具有以下字段

default（字符串）：这是一个必填字段，如果未提供其他值，则应使用此值。
enum（字符串数组）：如果存在，此数组列出变量的有效值（并且 default 值必须在数组中）。
description（字符串）：文档始终有助于理解变量的目的。

因此，上面的示例可以扩展如下

servers:
- url: https://{username}.server.com:{port}/{version}
  variables:
    username:
      default: demo
      description: This value is assigned by the service provider.
    port:
      enum:
        - "8443"
        - "443"
      default: "8443"
    version:
      default: v1

注意：default 变量值的工作方式不同于 OpenAPI 规范其他部分中使用的默认架构对象值。后者是可选的，这意味着如果未提供架构对象值，则应假定它是默认值。另一方面，服务器变量必须始终提供。

总结

此页面已显示

可以使用 servers 数组提供服务器列表。
此数组存在于不同的级别（OpenAPI 对象、路径项对象和操作对象），并且只使用最里面的数组。
服务器 URL 可以包含 variables 以进行进一步的自定义，例如 https://{username}.server.com:{port}/{version}