Skip to main content

Pyramid addon for OpenAPI3 validation

Project description

Validate Pyramid views against an OpenAPI 3.0 document

CircleCI for pyramid_openapi3 (master branch) Test coverage (master branch) Test coverage (master branch) latest version of pyramid_openapi3 on PyPI Supported Python versions License: MIT Built by these great folks! Talk to us in #pyramid on Freenode IRC

Peace of Mind

The reason this package exists is to give you peace of mind when providing a RESTful API. Instead of chasing down preventable bugs and saying sorry to consumers, you can focus on more important things in life.

  • Your API documentation is never out-of-date, since it is generated out of the API document that you write.
  • The documentation comes with try-it-out examples for every endpoint in your API. You don't have to provide (and maintain) curl commands to showcase how your API works. Users can try it themselves, right in their browsers.
  • Your API document is always valid, since your Pyramid app won't even start if the document does not comply with the OpenAPI 3.0 specification.
  • Automatic request payload validation and sanitization. Your views do not require any code for validation and input sanitation. Your view code only deals with business logic. Tons of tests never need to be written since every request, and its payload, is validated against your API document before it reaches your view code.
  • Your API responses always match your API document. Every response from your view is validated against your document and a 500 Internal Server Error is returned if the response does not exactly match what your document says the output of a certain API endpoint should be. This decreases the effects of Hyrum's Law.
  • A single source of truth. Because of the checks outlined above, you can be sure that whatever your API document says is in fact what is going on in reality. You have a single source of truth to consult when asking an API related question, such as "Remind me again, which fields are returned by the endpoint /user/info?".
  • Based on Pyramid, a mature Python Web framework. Companies such as Mozilla, Yelp, RollBar and SurveyMonkey trust Pyramid, and the new runs on Pyramid, too. Pyramid is thoroughly tested and documented, providing flexibility, performance, and a large ecosystem of high-quality add-ons.

Building Robust APIs


Getting started

  1. Declare pyramid_openapi3 as a dependency in your Pyramid project.

  2. Include the following lines:

config.pyramid_openapi3_spec('openapi.yaml', route='/api/v1/openapi.yaml')
  1. Use the openapi view predicate to enable request/response validation:
@view_config(route_name="foobar", openapi=True, renderer='json')
def myview(request):
    return request.openapi_validated.parameters

For requests, request.openapi_validated is available with two fields: parameters and body. For responses, if the payload does not match the API document, an exception is raised.

Advanced configuration

Relative File References in Spec

A feature introduced in OpenAPI3 is the ability to use $ref links to external files (

To use this, you must ensure that you have all of your spec files in a given directory (ensure that you do not have any code in this directory as all the files in it are exposed as static files), then replace the pyramid_openapi3_spec call that you did in Getting Started with the following:

config.pyramid_openapi3_spec_directory('path/to/openapi.yaml', route='/api/v1/spec')

Some notes:

  • Do not set the route of your pyramid_openapi3_spec_directory to the same value as the route of pyramid_openapi3_add_explorer.
  • The route that you set for pyramid_openapi3_spec_directory should not contain any file extensions, as this becomes the root for all of the files in your specified filepath.
  • You cannot use pyramid_openapi3_spec_directory and pyramid_openapi3_spec in the same app.

Endpoints / Request / Response Validation

Provided with pyramid_openapi3 are a few validation features:

  • incoming request validation (i.e., what a client sends to your app)
  • outgoing response validation (i.e., what your app sends to a client)
  • endpoint validation (i.e., your app registers routes for all defined API endpoints)

These features are enabled as a default, but you can disable them if you need to:

config.registry.settings["pyramid_openapi3.enable_endpoint_validation"] = False
config.registry.settings["pyramid_openapi3.enable_request_validation"] = False
config.registry.settings["pyramid_openapi3.enable_response_validation"] = False

Warning: Disabling request validation will result in request.openapi_validated no longer being available to use.

Register Pyramid's Routes

You can register routes in your pyramid application. First, write the x-pyramid-route-name extension in the PathItem of the OpenAPI schema.

    x-pyramid-route-name: foo_route
          description: GET foo

Then put the config directive pyramid_openapi3_register_routes in the app_factory of your application.


This means is equals to

config.add_route("foo_route", pattern="/foo")

Demo / Examples

There are three examples provided with this package:

Both examples come with tests that exhibit pyramid_openapi's error handling and validation capabilities.

A fully built-out app, with 100% test coverage, providing a API is available at niteoweb/pyramid-realworld-example-app. It is a Heroku-deployable Pyramid app that provides an API for a social app. You are encouraged to use it as a scaffold for your next project.

Design defense

The authors of pyramid_openapi3 believe that the approach of validating a manually-written API document is superior to the approach of generating the API document from Python code. Here are the reasons:

  1. Both generation and validation against a document are lossy processes. The underlying libraries running the generation/validation will always have something missing. Either a feature from the latest OpenAPI specification, or an implementation bug. Having to fork the underlying library in order to generate the part of your API document that might only be needed for the frontend is unfortunate.

    Validation on the other hand allows one to skip parts of validation that are not supported yet, and not block a team from shipping the document.

  2. The validation approach does sacrifice DRY-ness, and one has to write the API document and then the (view) code in Pyramid. It feels a bit redundant at first. However, this provides a clear separation between the intent and the implementation.

  3. The generation approach has the drawback of having to write Python code even for parts of the API document that the Pyramid backend does not handle, as it might be handled by a different system, or be specific only to documentation or only to the client side of the API. This bloats your Pyramid codebase with code that does not belong there.

Running tests

You need to have pipenv and Python 3.7, 3.8, or 3.9 installed on your machine. Then you can run:

$ make tests

Related packages

These packages tackle the same problem-space:

  • pyramid_oas3 seems to do things very similarly to pyramid_openapi3, but the documentation is not in English and we sadly can't fully understand what it does by just reading the code.
  • pyramid_swagger does a similar thing, but for Swagger 2.0 documents.
  • connexion takes the same "write spec first, code second" approach as pyramid_openapi3, but is based on Flask.
  • bottle-swagger takes the same "write spec first, code second" approach too, but is based on Bottle.
  • pyramid_apispec uses generation with help of apispec and the marshmallow validation library. See above why we prefer validation instead of generation.

Deprecation policy

We do our best to follow the rules below.

  • Support the latest few releases of Python, currently Python 3.7, 3.8, and 3.9.
  • Support the latest few releases of Pyramid, currently 1.10.7 through 2.0.
  • Support the latest few releases of openapi-core, currently 0.13.4 through 0.13.8.
  • See Pipfile.lock for a frozen-in-time known-good-set of all dependencies.

Use in the wild

A couple of projects that use pyramid_openapi3 in production:


0.14 (2022-05-05)

  • Upgrade Swagger UI to latest version to get security fixes missing in the old release. [am-on]

0.13 (2021-06-13)

  • Add support for Pyramid 2.0 refs #133, #142. [lkuchenb, zupo]

0.12 (2021-06-07)

  • Basic support for multipart requests, refs #122. [Wim-De-Clercq]

  • Automatic route registration via x-pyramid-route-name extension, refs #46. [gjo]

  • Support for Python 3.9, refs #115. [stevepiercy, zupo]

  • Cleanup old relative OpenAPI server URL workaround. Drop support for openapi-core 0.13.1, refs #127, #129, #131. [sevanteri, zupo]

  • Fix KeyError when having multiple routes for a single path, refs #118. [damonhook]

0.11 (2021-02-15)

  • Allow setting permission for explorer and spec view. [sweh]

  • Allow multiple OpenApis in one pyramid application. [sweh]

  • Fix for route validation when used with pyramid route_prefix_context. [damonhook]

0.10.2 (2020-10-27)

  • Support for endpoint validation of prefixed routes. [zupo]

0.10.1 (2020-10-26)

  • Support disabling of endpoint validation via INI files. [zupo]

0.10.0 (2020-10-26)

  • Allow relative file $ref links in OpenApi spec, refs #93. [damonhook]

  • Validate that all endpoints in the spec have a registered route, refs #21. [phrfpeixoto]

0.9.0 (2020-08-16)

  • Add support for openapi-core 0.13.4. [sjiekak]

  • Add the ability to toggle request/response validation independently through registry settings. [damonhook]

0.8.3 (2020-06-21)

  • Brown-bag release. [zupo]

0.8.2 (2020-06-21)

  • Raise a warning when a bad API spec causes validation errors to be discarded. [matthewwilkes]

  • Fix custom_formatters support in latest openapi-core 0.13.3. [simondale00]

  • Declare a minimal supported version of openapi-core. [zupo]

0.8.1 (2020-05-03)

  • Fix extract_errors to support lists, refs #75. [zupo]

0.8.0 (2020-04-20)

  • Log Response validation errors as errors, instead of warnings. [zupo]

  • Log Request validation errors as warnings, instead of infos. [zupo]

0.7.0 (2020-04-03)

  • Better support for handling apps mounted at subpaths. [mmerickel]

  • Pass the response into the response validation exception to support use-cases where we can return the response but log the errors. [mmerickel]

  • Reload development server also when YAML file changes. [mmerickel]

0.6.0 (2020-03-19)

  • Better support for custom formatters and a test showcasing how to use them. [zupo]

0.5.2 (2020-03-16)

  • Bad JWT tokens should result in 401 instead of 400. [zupo]

0.5.1 (2020-03-13)

0.5.0 (2020-03-07)

  • [BREAKING CHANGE] Move openapi_validation_error from examples/todoapp into the main package so it becomes a first-class citizen and people can use it without copy/pasting. If you need custom JSON rendering, you can provide your own extract_errors function via pyramid_openapi3_extract_errors config setting. [zupo]

  • Upgrade openapi-core to 0.13.x which brings a complete rewrite of the validation mechanism that is now based on jsonschema library. This manifests as different validation error messages.

    [BREAKING CHANGE] By default, openapi-core no longer creates models from validated data, but returns dicts. More info on [zupo]

0.4.1 (2019-10-22)

0.4.0 (2019-08-05)

  • Fix handling parameters in Headers and Cookies. [gweis]

  • Introduce RequestValidationError and ResponseValidationError exceptions in favor of pyramid_openapi3_validation_error_view directive. [gweis]

0.3.0 (2019-05-22)

  • Added type hints. [zupo]
  • Added additional references to other packages covering the same problem-space. [zupo]
  • Moved repo to Pylons GitHub organization. [stevepiercy, zupo]
  • Added a more built-out TODO-app example. [zupo]

0.2.8 (2019-04-17)

  • Fix for double-registering views. [zupo]
  • Added a single-file example. [zupo]

0.2.7 (2019-04-14)

  • Tweaking the release process. [zupo]

0.2.6 (2019-04-14)

  • Added a bunch of tests. [zupo]

0.2.5 (2019-04-08)

  • Automatic releases via CircleCI. [zupo]

0.1.0 (2019-04-08)

  • Initial release. [zupo]

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

pyramid_openapi3-0.14.tar.gz (36.4 kB view hashes)

Uploaded source

Built Distribution

pyramid_openapi3-0.14-py2.py3-none-any.whl (34.7 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page