Skip to main content

Swagger/OpenAPI 2.0 Parser

Project description

Posix Build Status Windows Build Status Docs License PyPI Python Versions Package Format Package Status

Prance provides parsers for Swagger/OpenAPI 2.0 and 3.0 API specifications in Python. It uses flex, swagger_spec_validator or openapi_spec_validator to validate specifications, but additionally resolves JSON references in accordance with the OpenAPI spec.

Mostly the latter involves handling non-URI references; OpenAPI is fine with providing relative file paths, whereas JSON references require URIs at this point in time.


Command Line Interface

After installing prance, a CLI is available for validating (and resolving external references in) specs:

# Validates with resolving
$ prance validate path/to/swagger.yml

# Validates without resolving
$ prance validate --no-resolve path/to/swagger.yml

# Validates and resolves, and writes the results to output.yaml
$ prance validate -o output.yaml path/to/swagger.yml

# Fetch URL, validate and resolve.
$ prance validate
Processing ""...
 -> Resolving external references.
Validates OK as Swagger/OpenAPI 2.0!

There is an interesting side effect to validation with an output file: when references are also resolved (the default), the output file effectively becomes a compiled spec in which all previous references are resolved.


Most likely you have spec file and want to parse it:

from prance import ResolvingParser
parser = ResolvingParser('path/to/my/swagger.yaml')
parser.specification  # contains fully resolved specs as a dict

Prance also includes a non-resolving parser that does not follow JSON references, in case you prefer that.

from prance import BaseParser
parser = BaseParser('path/to/my/swagger.yaml')
parser.specification  # contains specs as a dict still containing JSON references

On Windows, the code reacts correctly if you pass posix-like paths (/c:/swagger) or if the path is relative. If you pass absolute windows path (like c:\swagger.yaml), you can use prance.util.fs.abspath to convert them.

URLs can also be parsed:

parser = ResolvingParser('')

Largely, that’s it. There is a whole slew of utility code that you may or may not find useful, too. Look at the full documentation for details.


Different validation backends support different features.

Backend Python Version OpenAPI Version Strict Mode Notes Available From Link
swagger-spec-validator 2 and 3 2.0 only yes Slow; does not accept integer keys (see strict mode). prance 0.1 swagger_spec_validator
flex 2 and 3 2.0 only n/a Fastest; the default, and always required. prance 0.8 flex
openapi-spec-validator 3 only 2.0 and 3.0 yes Slow; does not accept integer keys (see strict mode). prance 0.12 openapi_spec_validator

You can select the backend in the constructor of the parser(s):

parser = ResolvingParser('', backend = 'swagger-spec-validator')

A note on strict mode: The OpenAPI specs are a little ambiguous. On the one hand, they use JSON references and JSON schema a fair bit. But on the other hand, what they specify as examples does not always match the JSON specs.

Most notably, JSON only accepts string keys in objects. However, some keys in the specs tend to be integer values, most notably the status codes for responses. Strict mode rejects non-string keys; the default lenient mode accepts them.

Since the flex validator is not based on JSON, it does not have this issue. The strict option therefore does not apply here.


Prance includes the ability to reference outside swagger definitions in outside Python packages. Such a package must already be importable (i.e. installed), and be accessible via the ResourceManager API (some more info here).

For example, you might create a package common_swag with the file base.yaml containing the definition

    type: string
    - INFO
    - WARN
    - ERROR
    - FATAL

In the for common_swag you would add lines such as

package_dir={'': 'src'},
    '': '*.yaml'

Then, having installed common_swag into some application, you could now write

    type: object
        $ref: 'python://common_swag/base.yaml#/definitions/Severity'
        type: string
        type: string
        type: string
    - severity
    - summary


See for details.


Licensed under MITNFA (MIT +no-false-attribs) License. See the LICENSE.txt file for details.

Project details

Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
prance-0.11.0-py2.py3-none-any.whl (22.6 kB) Copy SHA256 hash SHA256 Wheel py2.py3
prance-0.11.0.tar.gz (313.5 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page