FAQ

  • GitHub GitHub Repo stars
  • Discord Discord Server
  • oas2-valid-schema-example


    Formats: Severity:

    This rule was removed in v0.7.0 of vacuum.

    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!