Skip to content

parameter-description.md

Latest commit

 

History

History
78 lines (58 loc) · 1.83 KB

parameter-description.md

File metadata and controls

78 lines (58 loc) · 1.83 KB
slug /docs/cli/rules/oas/parameter-description

parameter-description

Ensure that every parameter has a description.

OAS Compatibility
2.0 ✅
3.0 ✅
3.1 ✅
3.2 ✅

API design principles

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!

Configuration

Option Type Description
severity string Possible values: off, warn, error. Default off (in recommended configuration).

An example configuration:

rules:
  parameter-description: error

Examples

Given this configuration:

rules:
  parameter-description: error

Example of an incorrect parameter:

paths:
  /customers/{id}:
    post:
      parameters:
        - name: id
          in: path
          required: true

Example of a correct parameter:

paths:
  /customers/{id}:
    post:
      parameters:
        - name: id
          in: path
          required: true
          description: The customer's ID.

Related rules

Resources