Pyramid integration with openapi-core and openapi-spec-validator
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
pyramid_openapi3 Allow declaring custom formatters (#5) Sep 13, 2018
tests
.gitignore Initial commit Jun 22, 2018
.travis.yml
CHANGELOG.md Initial commit Jun 28, 2018
MANIFEST.in
README.md
demo.py
demo.yaml
pytest.ini Add travis-ci (#1) Jun 28, 2018
setup.cfg
setup.py Add travis-ci (#1) Jun 28, 2018
tox.ini Add travis-ci (#1) Jun 28, 2018

README.md

pyramid_openapi3

Build Status PyPi

Validate OpenAPI 3.0 specification against pyramid framework configuration and views.

Features

Getting started

  1. Put pyramid_openapi3 as a dependency in your pyramid project.

  2. Include the following lines:

config.include("pyramid_openapi3")
config.pyramid_openapi3_spec('demo.yaml', route='/api/v1/openapi.yaml')
config.pyramid_openapi3_add_explorer(route='/api/v1/')
  1. In order 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 api specification is not valid, an exception will be raised.

Demo

$ pip install -e .[dev]
$ python demo.py

There's also a self-contained TODO app example.

Why? - Design defense

pyramid_openapi3 uses validation of the spec instead of generation:

a) Generating or validating against a spec is a lossy process, there will always be something missing. Having to write code for a library in order to generate the specification that might be just needed for the frontend is unfortunate. Validation on the other hand allows one to skip validation if it's not written, but it's not blocking a team from shipping the spec.

b) Validation approach does sacrifice DRY-ness, one has to write the spec and then the api in pyramid. This does have some good effects like when reviewing code the intent and result are both present.

c) If it chose generation, there's a drawback how to support knobs for features that pyramid doesn't have or are specific only to documentation or client side of the api. Feels like something that doesn't belong to the backend.

Running tests

$ tox

Related projects

  • pyramid_swagger does a similar thing, but for Swagger 2.0 specification
  • pyramid_apispec uses generation with help of apispec and marshmallow validation library