oas3-missing-example
Examples are really important. When defining an OpenAPI specification, it’s critical that every operation request and response have examples defined for them. The same applies to definitions defined as references.
Examples help consumers of your API understand what real data should actually look like when sending requests, or listening for responses.
Good examples are particularly valuable when data is complex, deep, nested or contains special formatting.
Why did this violation appear?
The specification is missing examples in one or more areas. Examples need to be added everywhere for this rule to pass.
What is this rule checking for?
The rule looks through the spec at the following elements, and checks that examples have been clearly defined for each.
- All Schemas
- All Parameters
- All Headers
- All Media Types
What does a good example look like?
In OpenAPI 3.0, we should include examples for each RequestBody. We should also include examples for Responses, Components or Parameters
A good example, of a RequestBody and Response example looks like this:
paths:
/burgers:
post:
operationId: createBurger
tags:
- "Burgers"
summary: Create a new burger
description: A new burger for our menu, yummy yum yum.
requestBody:
description: Give us the new burger!
content:
application/json:
schema:
$ref: '#/components/schemas/Burger'
examples:
pbjBurger:
summary: A horrible, nutty, sticky mess.
value:
name: Peanut And Jelly
numPatties: 3
cakeBurger:
summary: A sickly, sweet, atrocity
value:
name: Chocolate Cake Burger
numPatties: 5
responses:
"200":
description: A tasty burger for you to eat.
content:
application/json:
schema:
$ref: '#/components/schemas/Burger'
examples:
quarterPounder:
summary: A yummy tasty two patty burger.
value:
name: Quarter Pounder with Cheese
numPatties: 1
filetOFish:
summary: A Cripsy Fish Sammich filled with ocean goodness.
value:
name: Filet-O-Fish
numPatties: 1
How do I fix this violation?
Examples are critical for consumers to be able to understand schemas and models defined by the spec.
Without examples, developers can’t understand the type of data the API will return in real life. Examples are turned into mocks and can provide a rich testing capability for APIs. Add detailed examples everywhere!
Add examples!