oas2-valid-schema-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.

• Operation Responses
• Operation Parameters
• Global Definitions
• Global Parameters
• Example Schema Check
• Use of value/externalValue

Validating the schema.

If the operation or component implementing an example is an object (not a primitive), then vacuum will validate the example matches the schema defined.

Checking value/externalValue

Examples can have an externalValue or a value, but they cannot have both.

What does a good example look like?

In OpenAPI 2.0, there is no way to include examples for a RequestBody, unlike in OpenAPI 3. This means that examples can only be added to Responses, Definitions or Parameters

A good example, of a Response example looks like this:

"/pet":
  post:
    produces:
    - application/json
    parameters:
    - in: body
      name: body
      description: Pet object that needs to be added to the store
      required: true
      schema:
        "$ref": "#/definitions/Pet"
    responses:
      '200':
        description: New pet was added
        examples:
          application/json:
            id: 12345
            name: My New Pet
            color: Brown
            type: Dog

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!