Skip to main content

Automatically generate swagger/OAS schemas from example api interactions.

Project description

Creating swagger/OAS specs for an existing api by hand is tedious and error-prone. swaggergenerator fixes this by creating schemas from example interactions:

Generation is a three step process. Here’s an example using httpbin:

import requests
from swaggergenerator import Generator, get_yaml

# 1: Create a Generator.
generator = Generator()

# 2: Provide one or more examples. They can be for different paths and verbs.
response = requests.get('')
generator.provide_example(response.request, response)

# 3: Generate a schema (specifically, a Swagger Paths Object).
print get_yaml(generator.generate_paths())
    description: TODO
    parameters: []
        description: TODO
          additionalProperties: false
              additionalProperties: false
              properties: {}
              type: object
              additionalProperties: false
                  type: string
                  type: string
                  type: string
                  type: string
                  type: string
                  type: string
              type: object
              type: string
              type: string
          type: object

You can install it with $ pip install swaggergenerator.

Generation details

Generally, the generated schemas err on the side of being too strict. For example, additionalProperties is always set to False and parameters are always required. The recommended workflow is to generate schemas, validate them against all interactions in your test suite, and iterate until tests pass.

Here are the swagger features you can expect to be generated:

  • path objects for arbitrary verb/path combinations

  • all-digit path parameters

  • complex path parameters (when given alongside an all-digit example)

  • request schemas for 2xx responses

  • response schemas for 2xx responses

  • references to existing definitions

Here are some swagger features that won’t be generated. If your api uses any of these, you’ll need to fix up your output manually:

  • nullable/polymorphic types

  • heterogeneous arrays

  • optional properties

  • additionalProperties != False


Inside your vitualenv:

$ cd swaggergenerator
$ pip install -e .
$ pip install -r requirements.txt

To run the tests:

$ py.test tests/

Project details

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page