schema-example-defined

This rule ensures that all non-trivial schemas have at least one example defined.

Rule Details

Providing examples for these schemas enhances the readability and understanding of the API’s structure.

The schema-example-defined rule is designed to ensure that all non-trivial schemas have at least one example defined. Non-trivial schemas include strings with a defined pattern property, objects, and arrays.

Configuration

None.

Examples

Good.

components:
  schemas:
    User:
      type: object
      properties:
        username:
          type: string
          pattern: "^[a-z0-9_-]{3,16}$"
      example:
        username: "john_doe"

Bad. It is not immediately visible what are valid values for the username field.

components:
  schemas:
    User:
      type: object
      properties:
        username:
          type: string
          pattern: "^[a-z0-9_-]{3,16}$"

When Not to Use It

We recommend to always enable this rule.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.