Examples are valid

Developers trying to integrate with your API will look at the examples in your OpenAPI documentation -- you want them to be accurate, and match the schemas.

Optic's examples ruleset makes sure every example in the OpenAPI specification matches the API schema:

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)

LintGPT Spectral