operation-description-defined
Since 0.0.1 · In the rulesets: Recommended at error, Strict at error, All at error
This rule checks that every operation has a description of at least 10 characters.
Rule details
The description is where an operation says what it does beyond its method and path: what the
list is filtered by, what a delete does to related resources, which errors to expect. Generated
documentation and clients show it; without it, the reader guesses. A placeholder such as TBD
is shorter than the minimum and reported too.
The rule reports Operation has no meaningful description.
Configuration
A positive integer: the minimal length of a description. 10 by default.
Configuration example. Descriptions of at least 20 characters.
commands:
lint:
rules:
operation-description-defined:
- warning
- 20
Examples
Good. The description says what the list holds and what can be done with it.
paths:
/users:
get:
description: Returns a paged list of users, filtered and sorted by the query parameters.
responses:
"200":
description: A page of users.
Bad. No description.
paths:
/users:
get:
responses:
"200":
description: A page of users.
Bad. A placeholder.
paths:
/users:
get:
description: TBD
responses:
"200":
description: A page of users.
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.rules has the details.
commands:
lint:
rules:
operation-description-defined: off