# schema-example-defined

Source: https://apigenie.pl/docs/linter/swagger/rules/schema-example-defined

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**.

```yaml
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.

```yaml
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.