host-defined

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error

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.

Turn the rule off for documents that are served by the API itself and are meant to be used against the host they are loaded from.

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: {}

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        host-defined: off

Related rules

Further reading

Was this helpful?