跳到内容

API 主机和基本路径

REST API 都有一个基本 URL，端点路径会附加到该 URL 上。基本 URL 在 API 规范的根级别通过 schemes、host 和 basePath 定义。

1
host: petstore.swagger.io
2
basePath: /v2
3
schemes:
4
    - https

所有 API 路径都是相对于此基本 URL 的，例如，/users 实际上意味着 <scheme>://<host>/<basePath>/users。

URL structure

schemes

schemes 是 API 使用的传输协议。Swagger 支持 http、https 和 WebSocket 协议——ws 和 wss。与 YAML 中的任何列表一样，`schemes` 可以使用列表语法指定

1
schemes:
2
    - http
3
    - https

或数组字面量语法

1
schemes: [http, https]

如果未指定 schemes，则将使用提供 API 规范的协议进行 API 调用。

host

host 是提供 API 的主机的域名或 IP 地址 (IPv4)。如果与协议的默认端口（HTTP 为 80，HTTPS 为 443）不同，它可能包含端口号。请注意，这必须只是主机名，不带 http(s):// 或子路径。有效主机

终端窗口
1
api.example.com
2
example.com:8089
3
93.184.216.34
4
93.184.216.34:8089

不正确

终端窗口
1
http://api.example.com
2
example.com/api/v1

如果未指定 host，则假定为主机与提供 API 文档的主机相同。

basePath

basePath 是所有 API 路径的 URL 前缀，相对于主机根目录。它必须以前导斜杠 / 开头。如果未指定 basePath，则默认为 /，即所有路径都从主机根目录开始。有效的基本路径

终端窗口
1
/v2
2
/api/v2
3
/

不正确

终端窗口
1
v2

忽略 host 和 scheme

host 和 schemes 可以省略，以实现更动态的关联。在这种情况下，用于提供 API 文档的主机和协议将用于 API 调用。例如，如果基于 Swagger UI 的文档托管在 https://api.example.com/apidocs/index.html，则“试用”API 调用将定向到 https://api.example.com。

常见问题

我可以指定多个主机吗，例如开发、测试和生产环境？

OpenAPI 3.0 支持多个主机。2.0 版每个 API 规范只支持一个 host（如果您将 HTTP 和 HTTPS 算作不同的主机，则为两个）。一种可能的方法是，从您的规范中省略 host 和 schemes，并从每个主机提供它。在这种情况下，规范的每个副本都将指向相应的主机。

host 和 basePath 支持模板化吗？例如
终端窗口
1
https://{customer_id}.saas-app.com/api/v1
2
https://api.saas-app.com/v1/{customer_id}/apis

OpenAPI 3.0 支持此功能，但 2.0 不支持。有关主机模板化的解决方法，请参阅上一个问题。

我可以为 HTTP 和 HTTPS 指定不同的端口吗？例如
终端窗口
1
http://example.com:8080
2
https://example.com:8443

OpenAPI 3.0 支持此功能，但 2.0 不支持。在 2.0 中，您可以省略 host 和 schemes，并从两个主机提供规范。这样，规范的每个副本都将指向用于访问该规范的主机和端口。

参考

host、basePath 和 schemes 字段

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

© . All rights reserved.