- 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.
examples standard to your
optic.dev.yml file. You can learn more about configuring your API standards here:
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.
The second part of standard is a bit more configurable: requiring examples for different parts of the OpenAPI.
boolean: all request bodies need to have an example
boolean: all response bodies need to have an example
boolean: all request parameters need to have an example