FAQ

  • GitHub GitHub Repo stars
  • Discord Discord Server
  • ✨ New! Try the OpenAPI Doctor ✨ The OpenAPI Doctor
    Recommended

    oas3-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: "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