Linter rulesSwagger 2.0host-defined

host-defined

Since 0.9.0

This rule checks whether a Swagger 2.0 document declares the host that serves the API.

Rule Details

Swagger 2.0 describes where an API is available with three root properties: host (the name or IP address, optionally with a port), basePath and schemes. When host is missing, tools fall back to the host that served the document, which is rarely what consumers want: generated clients and API consoles cannot reach the API without extra configuration.

The host-defined rule reports No host defined when the root host property is missing or empty. A basePath or schemes alone do not satisfy the rule. This is the Swagger 2.0 counterpart of the OpenAPI servers-defined rule.

Configuration

None.

Examples

Good. The host of the API is declared.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
host: api.example.com
basePath: /v1
schemes: [https]
paths: {}

Bad. Only the base path is declared.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
basePath: /v1
paths: {}

When Not to Use It

You may disable this rule for documents that are served by the API itself and are meant to be used against the host they are loaded from.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has the servers-defined rule.

Related rules

Further reading