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.
curlcommands to showcase how your API works. Users can try it themselves, right in their browsers.
500 Internal Server Erroris 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.
openapi.json) against the OpenAPI 3.0 specification using the openapi-spec-validator.
pyramid_openapi3 as a dependency in your Pyramid project.
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/')
openapiview predicate 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 the payload does not match the API document, an exception is raised.
A feature introduced in OpenAPI3 is the ability to use
$ref links to external files (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#referenceObject).
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:
pyramid_openapi3_spec_directoryto the same value as the
routethat you set for
pyramid_openapi3_spec_directoryshould not contain any file extensions, as this becomes the root for all of the files in your specified
pyramid_openapi3_specin the same app.
pyramid_openapi3 are a few validation features:
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_validatedno longer being available to use.
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 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.
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:
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.
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.
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.
You need to have pipenv and Python 3.7, 3.8, or 3.9 installed on your machine. Then you can run:
$ make tests
These packages tackle the same problem-space:
We do our best to follow the rules below.
openapi-coreand its sub-dependencies. See
Pipfile.lockfor a frozen-in-time known-good-set of all dependencies.
A couple of projects that use pyramid_openapi3 in production: