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 中的任何列表一样，可以使用列表语法指定方案

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 和 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 字段

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