schema-example-defined

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error

This rule ensures that the schemas of a Swagger 2.0 document provide examples.

Rule details

Examples make an API easier to understand, and are used by documentation tools, mock servers and API consoles.

The schema-example-defined rule checks:

  • every entry of definitions, reporting Schema does not define examples when it has no example,
  • the inline schema of every body parameter, reporting Body parameter schema does not define examples when it has no example,
  • the inline schema of every response, reporting Response schema does not define examples when it has no example and the response has no examples.

Schemas defined with a $ref are not reported: the referenced definition is checked instead. Schemas nested in other schemas (properties, items, …) are not checked.

The OpenAPI linter has a rule of the same name, schema-example-defined, for OpenAPI 3.x documents.

Turn the rule off if examples are provided outside the document.

Examples

Good.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths:
  /pets:
    post:
      parameters:
        - name: pet
          in: body
          required: true
          schema:
            $ref: '#/definitions/Pet'
      responses:
        '201':
          description: Created
          schema:
            type: object
            properties:
              id:
                type: integer
          examples:
            application/json:
              id: 42
definitions:
  Pet:
    type: object
    properties:
      name:
        type: string
    example:
      name: Rex

Bad. The inline body parameter schema and the PetId definition, used by the response, provide no examples.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths:
  /pets:
    post:
      parameters:
        - name: pet
          in: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/PetId'
definitions:
  PetId:
    type: object
    properties:
      id:
        type: integer

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        schema-example-defined: off

Related rules

Further reading

Was this helpful?