Skip to main content
  1. Consistent Casing Naming

OpenAPI examples must be valid

The best API documentation is full of examples. Schemas are important, but when it comes to actually making requests and understanding how your API will response, nothing beats examples. Over time your APIs will change and it is often difficult to keep the examples in your OpenAPI file in sync with the schemas. The only thing worse for your documentation than having no examples, is having examples that are wrong. Requiring up-to-date examples is one of the highest-impact standards you can adopt, especially if your OpenAPI document powers public documentation.

Usage

Add the examples standard to your optic.dev.yml file. You can learn more about configuring your API standards here:

optic.dev.yml
rulesets:
- examples:
require_request_examples: true
require_response_examples: true
require_parameter_examples: true

This standard requires that every example is the specification has to match its schema. If an example fails schema validation those are errors. After turning this rule on you may discover that some of your existing examples are invalid.

Requiring examples

The second part of standard is a bit more configurable: requiring examples for different parts of the OpenAPI.

require_request_examples (optional) boolean: all request bodies need to have an example require_response_examples (optional) boolean: all response bodies need to have an example require_parameter_examples (optional) boolean: all request parameters need to have an example

Issues and contributing

Help your developers ship better APIs

Optic makes it easy to track, review, and test every API change so your can build the right API, the first time.