operation-description-defined
Since 0.9.0 · In the rulesets: Recommended at error, Strict at error, All at error
This rule checks whether every operation of a Swagger 2.0 document has a meaningful description.
Rule details
A description tells consumers what an operation does, when to call it and what side effects it has. Generated documentation and clients show it next to the operation.
The operation-description-defined rule reports Operation has no meaningful description for every operation whose description is missing or shorter
than the configured minimal length (10 characters by default). The summary
property does not count as a description.
The OpenAPI linter has a rule of the same name, operation-description-defined, for OpenAPI 3.x documents.
Turn the rule off when operations are documented outside of the Swagger document.
Configuration
A single positive integer: the minimal number of characters of a description. The default is 10.
commands:
lint:
swagger:
rules:
operation-description-defined: [warning, 20]
Examples
Good. The operation has a meaningful description.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths:
/pets:
get:
description: Lists every pet of the store, ordered by name.
responses:
'200':
description: A list of pets.
Bad. The first operation has no description, the second one has a description that is too short.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths:
/pets:
get:
summary: List pets
responses:
'200':
description: A list of pets.
post:
description: Adds
responses:
'201':
description: The pet was added.
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:
operation-description-defined: off