Skip to content
Pyramid addon for OpenAPI3 validation of requests and responses.
Branch: master
Clone or download
Latest commit 8b86437 May 22, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Add a slightly more built-out TODO app example Apr 22, 2019
.mypy more precise type_coverage.py arguments May 22, 2019
examples Migrate to Pylons org May 9, 2019
pyramid_openapi3 add type hints May 22, 2019
.aspell.en.pws dump a load of opinions on how to develop python projects Apr 8, 2019
.coveragerc dump a load of opinions on how to develop python projects Apr 8, 2019
.editorconfig dump a load of opinions on how to develop python projects Apr 8, 2019
.flake8 dump a load of opinions on how to develop python projects Apr 8, 2019
.gitattributes dump a load of opinions on how to develop python projects Apr 8, 2019
.gitignore upgrade dev env to latest versions May 22, 2019
.isort.cfg dump a load of opinions on how to develop python projects Apr 8, 2019
.pre-commit-config.yaml dump a load of opinions on how to develop python projects Apr 8, 2019
CHANGELOG.md release 0.3.0 May 22, 2019
CONTRIBUTING.md Migrate to Pylons org May 9, 2019
LICENSE add LICENSE file Apr 7, 2019
MANIFEST.in Initial commit Jun 28, 2018
Makefile add type hints May 22, 2019
Pipfile upgrade dev env to latest versions May 22, 2019
Pipfile.lock upgrade dev env to latest versions May 22, 2019
README.md add type hints May 22, 2019
RELEASE.md Migrate to Pylons org May 9, 2019
header.jpg upload header logos Apr 7, 2019
setup.cfg add type hints May 22, 2019
setup.py release 0.3.0 May 22, 2019
tox.ini Add travis-ci (#1) Jun 28, 2018

README.md

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 is not according to 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.
  • 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 does the endpoint /user/info return?".
  • Based on Pyramid, a mature Python Web framework. Companies such as Mozilla, Yelp, RollBar and SurveyMonkey trust Pyramid, and the new pypi.org runs on Pyramid too. Pyramid is thoroughly tested and documented, providing flexibility, performance, and a large ecosystem of high-quality add-ons.

Features

Getting started

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

  2. Include the following lines:

config.include("pyramid_openapi3")
config.pyramid_openapi3_spec('openapi.yaml', route='/api/v1/openapi.yaml')
config.pyramid_openapi3_add_explorer(route='/api/v1/')
  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.

Demo / Examples

There are two 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 RealWorld.io API is available at niteoweb/pyramid-realworld-example-app. It is a Heroku-deployable Pyramid app that provides an API for a Medium.com-like 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:

a) 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.

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

c) 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 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 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 marshmallow validation library. See above why we prefer validation instead of generation.

Use in the wild

A couple of projects that use pyramid_openapi3 in production:

  • WooCart API - Users' control panel for WooCart Managed WooCommerce service.
You can’t perform that action at this time.