API 服務(wù)器

如果在 API 文檔中，能夠列出提供 API 的服務(wù)地址，就會(huì)非常有助于開發(fā)和測(cè)試。

服務(wù)器對(duì)象

OpenAPI 提供了服務(wù)器對(duì)象（Server Object），能夠描述 API 的基礎(chǔ)服務(wù)地址。每個(gè)服務(wù)器對(duì)象至少包含一個(gè)url 字段，表示基礎(chǔ)服務(wù)地址；還可以包含一個(gè)可選的description 字段，對(duì)服務(wù)器的用途等情況進(jìn)行詳細(xì)描述。

在 OpenAPI 根對(duì)象下，有一個(gè)服務(wù)器對(duì)象集合字段：servers，可以包含一個(gè)或多個(gè)服務(wù)器對(duì)象。

servers:
- url: http://dev.topeid.com/v1
  description: 開發(fā)服務(wù)器。
- url: http://prod.topeid.com/v1
  description: 生產(chǎn)服務(wù)器。
- url: http://test.topeid.com/v1
  description: 測(cè)試服務(wù)器。

還記得前面文章中介紹的 Paths 對(duì)象嗎？Paths 對(duì)象中的每一個(gè)端點(diǎn)，都可以附加在基礎(chǔ)服務(wù)地址后面，構(gòu)成完整的端點(diǎn)地址。

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

上面文檔片段所描述的完整端點(diǎn)地址是：http://topeid.com/v1/users.

我們可以在 API 文檔中不同地方添加 servers 字段。如果 API 文檔中出現(xiàn)了多個(gè) servers 字段，則文檔中層級(jí)最低的 servers 字段起作用。例如：

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

在上面的文檔片段示例中，/users 端點(diǎn)的 GET 請(qǐng)求服務(wù)地址是：http://topeid2.com/users，而不是 http://topeid1.com/users.

服務(wù)器變量

在服務(wù)器的基礎(chǔ)服務(wù)地址（URL）中，可以使用變量進(jìn)行描述。每一個(gè)變量必須使用{}包起來(lái)。

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

所有服務(wù)器變量必須在 variables 字段中進(jìn)行賦值和描述。服務(wù)器變量可以使用下列字段進(jìn)行描述：

• default (字符串): 強(qiáng)制字段，默認(rèn)值。
• enum (字符串?dāng)?shù)組): 可選字段, 列出了變量有效取值范圍。注意：默認(rèn)值必須在數(shù)組中。
• description (字符串): 可選字段，對(duì)變量進(jìn)行額外說(shuō)明。

更完整對(duì)示例如下：

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

小結(jié)

1. 使用 servers 字段列出運(yùn)行 API 的服務(wù)器的基礎(chǔ)服務(wù)地址（URL）。
2. 在使用多個(gè) servers 字段的情況下，采用“就近原則”。
3. 服務(wù)器的 URL 可以包含變量。