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('https://httpbin.org/get')
generator.provide_example(response.request, response)

# 3: Generate a schema (specifically, a Swagger Paths Object).
print get_yaml(generator.generate_paths())
/get:
  get:
    description: TODO
    parameters: []
    responses:
      '200':
        description: TODO
        schema:
          additionalProperties: false
          properties:
            args:
              additionalProperties: false
              properties: {}
              type: object
            headers:
              additionalProperties: false
              properties:
                Accept:
                  type: string
                Accept-Encoding:
                  type: string
                Connection:
                  type: string
                Content-Length:
                  type: string
                Host:
                  type: string
                User-Agent:
                  type: string
              type: object
            origin:
              type: string
            url:
              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

Contributing

Inside your vitualenv:

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

To run the tests:

$ py.test tests/

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

swaggergenerator-0.0.3.tar.gz (8.0 kB view details)

Uploaded Source

File details

Details for the file swaggergenerator-0.0.3.tar.gz.

File metadata

File hashes

Hashes for swaggergenerator-0.0.3.tar.gz
Algorithm Hash digest
SHA256 c56d9b1a2fd058692abed8979a84ca1002b22e2692b77ce0848f3a36a56c65a7
MD5 ca367b8db57754f6453df6525ffd529e
BLAKE2b-256 87bdfda211827057efd8c7da689fcd8e3b6553cb793140aa49615bea46086a60

See more details on using hashes here.

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