no-invalid-parameter-examples

Disallow invalid parameter examples.

OAS Compatibility
2.0
3.0
3.1
components
compares schema
to example
NamedParameter
Root
Paths
PathItem
Operation
Parameter
Example
Schema

API design principles

If your parameter schema and example conflict, there is a problem in the definition of the schema or the example. Solve it before you ship it.

Configuration

Option Type Description
severity string Possible values: off, warn, error. Default warn.
allowAdditionalProperties boolean Determines if additional properties are allowed in examples. Default false.
Copy
Copied
rules:
  no-invalid-parameter-examples:
    severity: error
    allowAdditionalProperties: false

Examples

Given the following configuration:

Copy
Copied
rules:
  no-invalid-parameter-examples:
    severity: error
    allowAdditionalProperties: false

Example of incorrect parameter example:

Copy
Copied
paths:
  /results:
    get:
      summary: Search Chess Results
      operationId: searchChessResult
      parameters:
        - name: username
          in: query
          schema:
            type: string
            maxLength: 15
          description: Value to query the chess results against usernames
          example: ThisUsernameIsTooLong

Example of correct parameter example:

Copy
Copied
paths:
  /results:
    get:
      summary: Search Chess Results
      operationId: searchChessResult
      parameters:
        - name: username
          in: query
          schema:
            type: string
            maxLength: 10
          description: Value to query the chess results against usernames
          example: ella

Related rules

Resources