oas3-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: "Get a chicken nugget by ID"
      parameters:
        - in: path
          name: nuggetId
          schema:
            type: integer
          required: true
          ...

Good example

paths:
  /chicken/nuggets/{nuggetId}:
    get:
      summary: "Get a chicken nugget by ID"
      parameters:
        - in: path
          name: nuggetId
          schema:
            type: integer
          required: true
          description: "Numeric ID of the chicken nugget that you want to get"
        ...

How do I fix this violation?

Add a description to the parameter, make it meaningful - add value for the consumer.

Spectral Equivalent

The rule is equivalent to oas3-parameter-description