Examples in API schemas

If the schema contains parameter examples, then Schemathesis will include them in the generated cases.

Schemathesis supports the use of both OpenAPI example and examples keywords (more information available in the OpenAPI documentation). Note that the examples keyword was added in OpenAPI 3, but Schemathesis supports this feature for OpenAPI 2 via the x-examples extension.

paths:
  get:
    parameters:
    - in: body
      name: body
      required: true
      schema: '#/definitions/Pet'

definitions:
  Pet:
    additionalProperties: false
    example:
      name: Doggo
    properties:
      name:
        type: string
    required:
    - name
    type: object

With this Swagger schema example, there will be a case with body {"name": "Doggo"}. Schemathesis handle explicit examples with the hypothesis.example decorator. You can look up more info in the Hypothesis documentation.

Schemathesis also supports examples in individual properties.

...
paths:
  /users:
    parameters:
      - in: query
        name: foo
        schema:
          type: object
          properties:
            prop1:
              type: string
              example: prop1 example
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                foo:
                  type: string
                  example: bar

Don’t worry if you don’t have examples for all properties - Schemathesis will generate them for you.

External examples

Examples specified via the externalValue keyword are also supported:

content:
  application/json:
    schema:
      $ref: '#/components/schemas/MyObject'
    examples:
      jsonObject:
        summary: A sample object
        externalValue: 'http://example.com/examples/object-example.json'

Schemathesis will load external examples and cache them to avoid hitting the same URL multiple times during the same test run. Note that such examples for multipart/form-data are not supported because they require the boundary directive to be present. Schemathesis can’t infer it solely from the response.