- Validates OpenAPI3 file against openapi 3.0 specification using openapi-spec-validator
- Serves Swagger UI
- Validates request and response using openapi-core
pyramid_openapi3as a dependency in your pyramid project.
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/')
- In order to enable request/response validation:
@view_config(route_name="foobar", openapi=True, renderer='json') def myview(request): return request.openapi_validated.parameters
request.openapi_validated is available with two fields:
For responses, if api specification is not valid, an exception will be raised.
$ 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.