API 伺服器與基礎路徑

所有 API 端點都相對於基礎 URL。例如，假設基礎 URL 為 https://api.example.com/v1，則 /users 端點是指 https://api.example.com/v1/users。

1
https://api.example.com/v1/users?role=admin&status=active
2
\________________________/\____/ \______________________/
3
server URL       endpoint    query parameters
4
path

在 OpenAPI 3.0 中，您可以使用 servers 陣列來指定 API 的一個或多個基礎 URL。servers 取代了 OpenAPI 2.0 中使用的 host、basePath 和 schemes 關鍵字。每個伺服器都有一個 url 和一個可選的 Markdown 格式 description。

1
servers:
2
  - url: https://api.example.com/v1    # The "url: " prefix is required

您也可以有多個伺服器，例如生產環境和沙箱環境

1
servers:
2
  - url: https://api.example.com/v1
3
    description: Production server (uses live data)
4
  - url: https://sandbox-api.example.com:8443/v1
5
    description: Sandbox server (uses test data)

伺服器 URL 格式

伺服器 URL 格式遵循 RFC 3986，通常如下所示

1
scheme://host[:port][/path]

主機可以是名稱或 IP 位址 (IPv4 或 IPv6)。OpenAPI 2.0 中的 WebSocket 協定 ws:// 和 wss:// 也受到 OpenAPI 3.0 的支援。有效伺服器 URL 的範例

1
https://api.example.com
2
https://api.example.com:8443/v1/reports
3
http://localhost:3025/v1
4
http://10.0.81.36/v1
5
ws://api.example.com/v1
6
wss://api.example.com/v1
7
/v1/reports
8
/
9
//api.example.com

如果伺服器 URL 是相對的，則會根據給定 OpenAPI 定義檔案所託管的伺服器來解析（更多資訊請參閱下方）。注意：伺服器 URL 不得包含查詢字串參數。例如，這是無效的

1
https://api.example.com/v1?route=

如果未提供 servers 陣列或該陣列為空，則伺服器 URL 預設為 /

1
servers:
2
  - url: /

伺服器範本

伺服器 URL 的任何部分 – 協定、主機名稱或其部分、連接埠、子路徑 – 都可以使用變數參數化。變數在伺服器 URL 中以 {大括號} 表示，如下所示

1
servers:
2
  - url: https://{customerId}.saas-app.com:{port}/v2
3
    variables:
4
      customerId:
5
        default: demo
6
        description: Customer ID assigned by the service provider
7
      port:
8
        enum:
9
          - '443'
10
          - '8443'
11
        default: '443'

與路徑參數不同，伺服器變數不使用 schema。相反地，它們被假定為字串。變數可以有任意值，或可能被限制為 enum。在任何情況下，都需要 default 值，如果用戶端未提供值，則將使用該值。變數 description 是可選的，但很有用，並且支援 Markdown (CommonMark) 進行 RTF 格式設定。伺服器範本的常見使用案例

指定多個協定 (例如 HTTP 與 HTTPS)。
SaaS（託管）應用程式，其中每個客戶都有自己的子網域。
不同地理區域的區域伺服器 (範例：Amazon Web Services)。
用於 SaaS 和內部部署 API 的單一 API 定義。

範例

HTTPS 和 HTTP

1
servers:
2
  - url: http://api.example.com
3
  - url: https://api.example.com

或使用範本

1
servers:
2
  - url: '{protocol}://api.example.com'
3
    variables:
4
      protocol:
5
        enum:
6
          - http
7
          - https
8
        default: https

注意：這兩個範例在語意上是不同的。第二個範例明確將 HTTPS 伺服器設定為 default，而第一個範例沒有預設伺服器。

生產、開發和預備環境

1
servers:
2
  - url: https://{environment}.example.com/v2
3
    variables:
4
      environment:
5
        default: api    # Production server
6
        enum:
7
          - api         # Production server
8
          - api.dev     # Development server
9
          - api.staging # Staging server

SaaS 和內部部署

1
servers:
2
  - url: "{server}/v1"
3
    variables:
4
      server:
5
        default: https://api.example.com # SaaS server

不同地理區域的區域端點

1
servers:
2
  - url: https://{region}.api.cognitive.microsoft.com
3
    variables:
4
      region:
5
        default: westus
6
        enum:
7
          - westus
8
          - eastus2
9
          - westcentralus
10
          - westeurope
11
          - southeastasia

覆寫伺服器

全域 servers 陣列可以在路徑層級或操作層級覆寫。如果某些端點使用與 API 其餘部分不同的伺服器或基礎路徑，這會很方便。常見範例包括

用於檔案上傳和下載操作的不同基礎 URL，
已過時但仍可運作的端點。

1
servers:
2
  - url: https://api.example.com/v1
3

4
paths:
5
  /files:
6
    description: File upload and download operations
7
    servers:
8
      - url: https://files.example.com
9
        description: Override base path for all operations with the /files path
10
    ...
11

12
/ping:
13
    get:
14
      servers:
15
        - url: https://echo.example.com
16
          description: Override base path for the GET /ping operation

相對 URL

servers 陣列中的 URL 可以是相對的，例如 /v2。在這種情況下，URL 會根據託管給定 OpenAPI 定義的伺服器進行解析。這在託管於客戶自有伺服器上的內部部署安裝中非常有用。例如，如果託管於 http://localhost:3001/openapi.yaml 的定義指定 url: /v2，則 url 會解析為 http://localhost:3001/v2。相對 URL 解析規則遵循 RFC 3986。此外，API 定義中的幾乎所有其他 URL，包括 OAuth 2 流程端點、termsOfService、外部文件 URL 和其他，都可以指定為相對於伺服器 URL。

1
servers:
2
  - url: https://api.example.com
3
  - url: https://sandbox-api.example.com
4

5
# Relative URL to Terms of Service
6
info:
7
  version: 0.0.0
8
  title: test
9
  termsOfService: /terms-of-use
10

11
# Relative URL to external documentation
12
externalDocs:
13
  url: /docs
14
  description: Find more info here
15

16
# Relative URLs to OAuth2 authorization and token URLs
17
components:
18
  securitySchemes:
19
    oauth2:
20
      type: oauth2
21
      flows:
22
        authorizationCode:
23
          authorizationUrl: /oauth/dialog
24
          tokenUrl: /oauth/token

請注意，如果使用多個伺服器，則相對 URL 指定的資源預期存在於所有伺服器上。

參考資料

伺服器物件

URL 中的相對參考

找不到您要尋找的內容嗎？詢問社群發現錯誤？讓我們知道