Linter rulesSwagger 2.0schema-example-defined

schema-example-defined

Since 0.9.0

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.

Configuration

None.

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

When Not to Use It

You may disable this rule if examples are provided outside the document.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading