Documentation 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:
  - documentation:
      exclude_operations_with_extension: x-draft
      require_property_descriptions: true
      require_operation_summary: true
      require_operation_description: true
      require_operation_id: true
      required_on: added
      severity: 'warn'

Options

required_on always | added:

Do you want to make sure every operation follows these rules, or just new ones?

severity warn | info | error:

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

require_property_descriptions(default false): Are property descriptions required?

require_operation_summary(default false): Are operation summaries required?

require_operation_description(default false): Are operation descriptions required?

require_operation_id(default false): Are operation ids 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)