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) 进行富文本格式设置。服务器模板的常见用例

指定多个协议（例如 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 中的相对引用

没有找到您要找的内容？向社区提问发现错误？请告诉我们