API 服务器

如果在 API 文档中，能够列出提供 API 的服务地址，就会非常有助于开发和测试。

服务器对象

OpenAPI 提供了服务器对象（Server Object），能够描述 API 的基础服务地址。每个服务器对象至少包含一个url 字段，表示基础服务地址；还可以包含一个可选的description 字段，对服务器的用途等情况进行详细描述。

在 OpenAPI 根对象下，有一个服务器对象集合字段：servers，可以包含一个或多个服务器对象。

servers:
- url: http://dev.topeid.com/v1
  description: 开发服务器。
- url: http://prod.topeid.com/v1
  description: 生产服务器。
- url: http://test.topeid.com/v1
  description: 测试服务器。

还记得前面文章中介绍的 Paths 对象吗？Paths 对象中的每一个端点，都可以附加在基础服务地址后面，构成完整的端点地址。

servers:
- url: http://topeid.com/v1
paths:
  /users:
    get:

上面文档片段所描述的完整端点地址是：http://topeid.com/v1/users.

我们可以在 API 文档中不同地方添加 servers 字段。如果 API 文档中出现了多个 servers 字段，则文档中层级最低的 servers 字段起作用。例如：

servers:
- url: http://topeid1.com
paths:
  /users:
    get:
      servers:
      - url: http://topeid2.com

在上面的文档片段示例中，/users 端点的 GET 请求服务地址是：http://topeid2.com/users，而不是 http://topeid1.com/users.

服务器变量

在服务器的基础服务地址（URL）中，可以使用变量进行描述。每一个变量必须使用{}包起来。

servers:
- url: http://{username}.topeid.com:{port}/{version}

所有服务器变量必须在 variables 字段中进行赋值和描述。服务器变量可以使用下列字段进行描述：

• default (字符串): 强制字段，默认值。
• enum (字符串数组): 可选字段, 列出了变量有效取值范围。注意：默认值必须在数组中。
• description (字符串): 可选字段，对变量进行额外说明。

更完整对示例如下：

servers:
- url: https://{username}.topeid.com:{port}/{version}
  variables:
    username:
      default: demo
      description: 变量值由服务提供者指定。
    port:
      enum:
        - "8443"
        - "443"
      default: "8443"
    version:
      default: v1

小结

1. 使用 servers 字段列出运行 API 的服务器的基础服务地址（URL）。
2. 在使用多个 servers 字段的情况下，采用“就近原则”。
3. 服务器的 URL 可以包含变量。