parameter-description-defined
Since 0.0.1 · In the rulesets: Recommended at warning, Strict at warning, All at error
This rule checks that every parameter has a description of at least 10 characters that is not a placeholder.
Rule details
The name and the type of a parameter say what it holds; the description says what it does: which values are special, whether a filter is exact or prefix, how two parameters interact. Generated documentation shows it next to the parameter, and a client author reads it instead of trying.
The rule reports Parameter '...' has no meaningful description when the description is missing,
shorter than the minimum, white space only, or one of TBD, TODO and FIXME.
Configuration
A positive integer: the minimal length of a description. 10 by default.
Configuration example. Descriptions of at least 20 characters.
commands:
lint:
rules:
parameter-description-defined:
- warning
- 20
Examples
Good. The description says what the name does not.
paths:
/users/{id}:
get:
parameters:
- name: id
in: path
description: |
The ID of the user, or `self` for the user the request is authenticated as.
required: true
schema:
type: string
Bad. Nothing says that self is accepted.
paths:
/users/{id}:
get:
parameters:
- name: id
in: path
required: true
schema:
type: string
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:
parameter-description-defined: off