Swagger/OpenAPI 2.0 Parser
Project description
Prance provides parsers for Swagger/OpenAPI 2.0 API specifications in Python. It uses flex or swagger_spec_validator to validate specifications, but additionally resolves JSON references in accordance with the Swagger spec.
Mostly the latter involves handling non-URI references; Swagger is fine with providing relative file paths, whereas JSON references require URIs at this point in time.
Usage
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 http://petstore.swagger.io/v2/swagger.json
Processing "http://petstore.swagger.io/v2/swagger.json"...
-> 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.
Code
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 dictPrance 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 referencesOn 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('http://petstore.swagger.io/v2/swagger.json')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.
Compatibility
As of version 0.8, we’re using flex as the default validation backend. The previous swagger-spec-validator still works, if you installed with the ssv dependencies.
You can select the backend in the constructor of the parser(s):
parser = ResolvingParser('http://petstore.swagger.io/v2/swagger.json', backend = 'swagger-spec-validator')Note that the flex validator simply accepts integer status codes, despite them not being valid JSON. See issue #5 for details. Therefore, flex also does not support the strict option.
Extensions
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
definitions:
Severity:
type: string
enum:
- INFO
- WARN
- ERROR
- FATALIn the setup.py for common_swag you would add lines such as
packages=find_packages('src'),
package_dir={'': 'src'},
package_data={
'': '*.yaml'
}Then, having installed common_swag into some application, you could now write
definitions:
Message:
type: object
properties:
severity:
$ref: 'python://common_swag/base.yaml#/definitions/Severity'
code:
type: string
summary:
type: string
description:
type: string
required:
- severity
- summaryContributing
See CONTRIBUTING.md for details.
License
Licensed under MITNFA (MIT +no-false-attribs) License. See the LICENSE.txt file for details.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for prance-0.10.1-py2.py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | ed533d00fba9629e5dc6731393c0e563228c70b187d4743e301de3e7a6495b8a |
|
| MD5 | 100aa8076ece8706dff7a7608b6d90c6 |
|
| BLAKE2b-256 | 61670d35bed4066aa2b257b43938a9a584cf3866e9e7d7bd2fbde36efbbbd240 |
