OAS 2 此页面适用于 OpenAPI 规范版本 2（以前称为 Swagger）。要了解最新版本，请访问 OpenAPI 3 页面.

API 主机和基本 URL

REST API 具有一个基本 URL，将端点路径附加到该基本 URL。基本 URL 由 API 规范根级别的 schemes、host 和 basePath 定义。

host: petstore.swagger.io
basePath: /v2
schemes:
  - https

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

方案

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

schemes:
  - http
  - https

或数组文字语法

schemes: [http, https]

如果未指定 schemes，则将使用用于提供 API 规范的方案来进行 API 调用。

主机

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

api.example.com
example.com:8089
93.184.216.34
93.184.216.34:8089

不正确

http://api.example.com
example.com/api/v1

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

基本路径

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

/v2
/api/v2
/

不正确

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，然后提供规范。在这种情况下，每个规范副本都将针对相应的主机。

主机和 basePath 是否支持模板？例如

https://{customer_id}.saas-app.com/api/v1
https://api.saas-app.com/v1/{customer_id}/apis

这在 OpenAPI 3.0 中受支持，但在 2.0 中不受支持。有关主机模板的解决方法，请参阅上一个问题。

我能否为 HTTP 和 HTTPS 指定不同的端口？例如

http://example.com:8080
https://example.com:8443

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

参考

主机、basePath 和方案字段

  

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