oas2-parameter-description

Formats:

Severity:

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