Ensure that every parameter has a description.
| OAS | Compatibility |
|---|---|
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
A parameter should have a description because documentation is important. That parameter filter that is self-documenting and intuitive is the same filter that you need to look into the source code to determine what kind of values to provide to it 7 months from now. Document it!
| Option | Type | Description |
|---|---|---|
| severity | string | Possible values: off, warn, error. Default off (in recommended configuration). |
An example configuration:
rules:
parameter-description: errorGiven this configuration:
rules:
parameter-description: errorExample of an incorrect parameter:
paths:
/customers/{id}:
post:
parameters:
- name: id
in: path
required: trueExample of a correct parameter:
paths:
/customers/{id}:
post:
parameters:
- name: id
in: path
required: true
description: The customer's ID.