Examples are accurate

Documented Examples match the current schema

Sometimes examples in the spec can drift. This ruleset ensures that examples always match the schema they are associated with

ruleset:
  - examples:
      exclude_operations_with_extension: x-draft
      require_request_examples: true
      require_response_examples: true
      require_parameter_examples: true
      required_on: added
      severity: 'warn'

Options

required_on always | added:

Do you want to make sure every example matches the schema, or just new ones? We suggest using always, it may create some up-front work, but it will make your docs a lot better.

severity warn | info | error:

Should invalid examples be a warning, error or info status. Errors cause CI to exit 1.

require_request_examples(default true): Are request body examples required?

require_response_examples(default true): Are response body examples required?

require_parameter_examples(default true): Are query, header, and cookie parameter examples required?

exclude_operations_with_extension (optional): Sometimes you do not want documentation checks to run on certain endpoints, if so, you can exclude these endpoints with a certain extension (e.g. any operation with the x-draft key)