oas2-parameter-description
This rule checks that Parameters contain a description.
Descriptions for parameters are really important. Documentation generation tools use this description as the main bulk of the documentation for describing what a parameter does and its effect.
It’s amazing how often API authors leave this blank or don’t put anything meaningful in here.
Why did this violation appear?
One Parameter or more are missing a description.
Bad example
paths:
/chicken/nuggets/{nuggetId}:
get:
summary: "Gets a chicken nugget by ID."
parameters:
- in: path
name: nuggetId
- in: query
name: addSauce
...
Good example
paths:
/chicken/nuggets/{nuggetId}:
get:
summary: "Gets a chicken nugget by ID."
parameters:
- in: path
name: nuggetId
description: "Chicken nuggetId is the kebab-case name of the product."
- in: query
name: addSauce
description: "Set this to 'true' to add ketchup, leave blank otherwise."
...
How do I fix this violation?
Add a description to the parameter, make it meaningful.
Spectral Equivalent
The rule is equivalent to oas2-parameter-description