OAS 2 This page applies to OpenAPI Specification ver. 2 (fka Swagger). To learn about the latest version, visit OpenAPI 3 pages.
API Host and Base URL
REST APIs have a base URL to which the endpoint paths are appended. The base URL is defined by
basePath on the root level of the API specification.
All API paths are relative to this base URL, for example,
/users actually means
schemes are the transfer protocols used by the API. Swagger supports the
https, and WebSocket schemes –
wss. As with any lists in YAML, schemes can be specified using the list syntax:
or the array literal syntax:
schemes: [http, https]
schemes are not specified, the scheme used to serve the API specification will be used for API calls.
host is the domain name or IP address (IPv4) of the host that serves the API. It may include the port number if different from the scheme’s default port (80 for HTTP and 443 for HTTPS). Note that this must be the host only, without http(s):// or sub-paths. Valid hosts:
host is not specified, it is assumed to be the same host where the API documentation is being served.
basePath is the URL prefix for all API paths, relative to the host root. It must start with a leading slash
basePath is not specified, it defaults to
/, that is, all paths start at the host root. Valid base paths:
Omitting host and scheme
schemes can be omitted for a more dynamic association. In this case, the host and scheme used to serve the API documentation will be used for API calls. For example, if Swagger UI-based documentation is hosted at https://api.example.com/apidocs/index.html, "try it out" API calls will be directed to https://api.example.com.
Can I specify multiple hosts, e.g. development, test and production?
Multiple hosts are supported in OpenAPI 3.0. 2.0 supports only one
host per API specification (or two if you count HTTP and HTTPS as different hosts). A possible way to target multiple hosts is to omit the
schemes from your specification and serve it from each host. In this case, each copy of the specification will target the corresponding host.
Do host and basePath support templating? Such as:
This is supported in OpenAPI 3.0, but not in 2.0. For a workaround for host templating, see the previous question.
Can I specify different ports for HTTP and HTTPS? Such as:
This is supported in OpenAPI 3.0, but not in 2.0. In 2.0, you can omit the
schemes and serve the specification from both hosts. This way, each copy of the specification will target the host and port used to access that specification.
host, basePath and schemes fields
Did not find what you were looking for? Ask the community
Found a mistake? Let us know