跳到内容

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 3.0 也支持 OpenAPI 2.0 中的 WebSocket 方案 ws:// 和 wss://。有效服务器 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 中的相对引用

没有找到您要找的内容？咨询社区 发现错误？告诉我们

© . All rights reserved.