prance

https://prance.readthedocs.io/en/latest/
Admin
Prance is a Python library that provides parsers for Swagger/OpenAPI 2.0 and 3.0 API specifications....
Tokens:1,755
Snippets:20
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Prance via pip

Source: https://prance.readthedocs.io/en/latest/index

Installs the basic Prance package from PyPI using pip. Note that this only installs the core code; additional subpackages are required for full functionality.

```bash
$ pip install prance
```

--------------------------------

### Install Prance with recommended dependencies

Source: https://prance.readthedocs.io/en/latest/index

Installs Prance with recommended dependencies including a validation backend (osv), ICU support, and CLI functionality. This provides a more complete installation for typical usage.

```bash
$ pip install prance[osv,icu,cli]
```

--------------------------------

### Install and Validate OpenAPI/Swagger Spec via CLI with Specific Backend

Source: https://prance.readthedocs.io/en/latest/index

Provides command-line instructions to install a specific OpenAPI/Swagger validation backend (e.g., `openapi-spec-validator`) and then use the Prance CLI tool to validate a specification file with that backend.

```bash
$ pip install openapi-spec-validator
$ pip install prance
$ prance validate --backend=openapi-spec-validator path/to/spec.yml
```

--------------------------------

### Configure Python setup.py for YAML Package Data

Source: https://prance.readthedocs.io/en/latest/index

This Python snippet demonstrates how to configure `setup.py` to include YAML files as package data. It uses `find_packages` to locate source packages and `package_data` to ensure that all `.yaml` files within the package are included when the package is installed, making them accessible via `ResourceManager`.

```Python
packages=find_packages('src'),
package_dir={'': 'src'},
package_data={
    '': '*.yaml'
}

```

--------------------------------

### Install ICU and Python development libraries on Ubuntu/Debian

Source: https://prance.readthedocs.io/en/latest/index

Installs the necessary system-level development libraries for ICU Unicode Library and Python on Ubuntu or Debian-based systems. These are prerequisites for certain Prance features.

```bash
$ sudo apt-get install libicu-dev python3-dev # Ubuntu/Debian
```

--------------------------------

### Install ICU and Python development libraries on Fedora

Source: https://prance.readthedocs.io/en/latest/index

Installs the necessary system-level development libraries for ICU Unicode Library and Python on Fedora-based systems. These are prerequisites for certain Prance features.

```bash
$ sudo dnf install libicu-devel python3-devel # Fedora
```

--------------------------------

### Prance API Modules Overview

Source: https://prance.readthedocs.io/en/latest/index

This section provides an overview of the main modules and submodules within the Prance library. Each entry describes the primary functionality of the module, such as parsing Swagger/OpenAPI specs, defining mixins, converting specs, or providing utility functions for formats, file systems, iterators, resolvers, URLs, exceptions, and paths.

```APIDOC
prance: Prance implements parsers for Swagger/OpenAPI 2.0 and 3.0.0 API specs.
prance.mixins: Defines Mixins for parsers.
prance.convert: Functionality for converting from Swagger/OpenAPI 2.0 to OpenAPI 3.0.0.
prance.util.formats: This submodule contains file format related utility code for Prance.
prance.util.fs: This submodule contains file system utilities for Prance.
prance.util.iterators: This submodule contains specialty iterators over specs.
prance.util.resolver: This submodule contains a JSON inlining reference resolver.
prance.util.url: This submodule contains code for fetching/parsing URLs.
prance.util.exceptions: This submodule contains helpers for exception handling.
prance.util.path: This module contains code for accessing values in nested data structures.
```

--------------------------------

### Select Validation Backend for Prance Parser

Source: https://prance.readthedocs.io/en/latest/index

Demonstrates how to explicitly select a validation backend when initializing a Prance parser. This allows users to choose a specific validator like `openapi-spec-validator` for their OpenAPI/Swagger specifications.

```python
parser = ResolvingParser('http://petstore.swagger.io/v2/swagger.json', backend = 'openapi-spec-validator')
```

--------------------------------

### Compile Swagger/OpenAPI spec with Prance CLI

Source: https://prance.readthedocs.io/en/latest/index

Uses the Prance command-line interface to compile an input Swagger/OpenAPI specification into a fully resolved output specification. This creates a single, self-contained spec file.

```bash
# Compile spec
$ prance compile path/to/input.yml path/to/output.yml
```

--------------------------------

### Resolve HTTP and File References in OpenAPI/Swagger Spec

Source: https://prance.readthedocs.io/en/latest/index

Demonstrates how to resolve multiple types of references, specifically HTTP/HTTPS URLs and local file paths, by OR-ing the `RESOLVE_HTTP` and `RESOLVE_FILES` constants when initializing the `ResolvingParser`.

```python
from prance import ResolvingParser
from prance.util.resolver import RESOLVE_HTTP, RESOLVE_FILES

parser = ResolvingParser('/path/to/spec', resolve_types = RESOLVE_HTTP | RESOLVE_FILES)
```

--------------------------------

### Convert Swagger/OpenAPI spec to OpenAPI 3.0 with Prance CLI

Source: https://prance.readthedocs.io/en/latest/index

Uses the Prance command-line interface to convert an older Swagger/OpenAPI specification to the new OpenAPI 3.0 standard. This command requires an active internet connection as it utilizes the swagger2openapi web API.

```bash
# Convert spec
$ prance convert path/to/swagger.yml path/to/openapi.yml
```

--------------------------------

### Parse Local OpenAPI/Swagger Spec with ResolvingParser

Source: https://prance.readthedocs.io/en/latest/index

Demonstrates how to parse a local OpenAPI/Swagger specification file using Prance's `ResolvingParser`. This parser automatically resolves all JSON references within the specification, providing a fully resolved dictionary.

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

--------------------------------

### Parse Remote OpenAPI/Swagger Spec from URL

Source: https://prance.readthedocs.io/en/latest/index

Illustrates parsing an OpenAPI/Swagger specification directly from a URL using the `ResolvingParser`. This is useful for fetching and resolving remote specifications.

```python
parser = ResolvingParser('http://petstore.swagger.io/v2/swagger.json')
```

--------------------------------

### Validate Swagger/OpenAPI spec from URL with Prance CLI

Source: https://prance.readthedocs.io/en/latest/index

Fetches a Swagger/OpenAPI specification from a given URL, then validates it and resolves any external references. This is useful for validating remote specifications.

```bash
# Fetch URL, validate and resolve.
$ prance validate http://petstore.swagger.io/v2/swagger.json
```

--------------------------------

### Validate Swagger/OpenAPI spec with Prance CLI (resolving references)

Source: https://prance.readthedocs.io/en/latest/index

Uses the Prance command-line interface to validate a Swagger/OpenAPI specification. This command automatically resolves external references within the specification.

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

--------------------------------

### Parse Local OpenAPI/Swagger Spec with BaseParser (Non-Resolving)

Source: https://prance.readthedocs.io/en/latest/index

Shows how to use Prance's `BaseParser` to parse a local OpenAPI/Swagger specification file without resolving JSON references. The resulting specification dictionary will still contain the original references.

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

--------------------------------

### Validate Swagger/OpenAPI spec with Prance CLI (without resolving references)

Source: https://prance.readthedocs.io/en/latest/index

Uses the Prance command-line interface to validate a Swagger/OpenAPI specification. This command performs validation without resolving any external references.

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

--------------------------------

### Reference External Swagger/OpenAPI Definition in YAML

Source: https://prance.readthedocs.io/en/latest/index

This YAML snippet shows how to define a 'Message' object in a Swagger/OpenAPI specification that references an external definition. It uses the `python://` scheme to point to the 'Severity' enum defined in `base.yaml` within the `common_swag` Python package, demonstrating cross-package schema reuse.

```YAML
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
    - summary

```

--------------------------------

### Resolve Only HTTP References in OpenAPI/Swagger Spec

Source: https://prance.readthedocs.io/en/latest/index

Shows how to configure `ResolvingParser` to only resolve references that point to external HTTP/HTTPS URLs, while keeping local file or internal references intact. This uses `RESOLVE_HTTP` from `prance.util.resolver`.

```python
from prance import ResolvingParser
from prance.util.resolver import RESOLVE_HTTP

parser = ResolvingParser('/path/to/spec', resolve_types = RESOLVE_HTTP)
```

--------------------------------

### Define Swagger/OpenAPI Severity Enum in YAML

Source: https://prance.readthedocs.io/en/latest/index

This YAML snippet defines a 'Severity' enum within a Swagger/OpenAPI specification. It specifies the type as string and lists allowed values like INFO, WARN, ERROR, and FATAL. This definition can be referenced by other parts of the API specification.

```YAML
definitions:
  Severity:
    type: string
    enum:
    - INFO
    - WARN
    - ERROR
    - FATAL

```
Tokens:
Raw