no-invalid-parameter-examples

Disallow invalid parameter examples.

OAS Compatibility
2.0
3.0
3.1
components
compares schema
to example
NamedParameter
Root
PathMap
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.
disallowAdditionalProperties boolean Determines if additional properties are allowed in examples. Default true.
Copy
Copied
styleguide:
  rules:
    no-invalid-parameter-examples:
      severity: error
      disallowAdditionalProperties: true

Examples

Given the following configuration:

Copy
Copied
styleguide:
  rules:
    no-invalid-parameter-examples:
      severity: error
      disallowAdditionalProperties: true

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