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