From 6b00be51313e05864dfa66f166f3cb42350568b3 Mon Sep 17 00:00:00 2001 From: p1c2u Date: Sat, 18 Feb 2023 18:05:08 +0000 Subject: [PATCH] documentation improvements --- CONTRIBUTING.md | 47 ---------------- CONTRIBUTING.rst | 1 + README.rst | 117 ++++++++++++--------------------------- docs/conf.py | 11 ++-- docs/contributing.rst | 76 +++++++++++++++++++++++++ docs/customizations.rst | 6 +- docs/index.rst | 100 ++++++++++++++++++++++++--------- docs/installation.rst | 15 ----- docs/integrations.rst | 52 +++++++++--------- docs/security.rst | 36 ++++++++++++ docs/unmarshalling.rst | 117 +++++++++++++++++++++++++++++++++++++++ docs/usage.rst | 119 ---------------------------------------- docs/validation.rst | 90 ++++++++++++++++++++++++++++++ 13 files changed, 463 insertions(+), 324 deletions(-) delete mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.rst create mode 100644 docs/contributing.rst delete mode 100644 docs/installation.rst create mode 100644 docs/security.rst create mode 100644 docs/unmarshalling.rst delete mode 100644 docs/usage.rst create mode 100644 docs/validation.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 347480e0..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,47 +0,0 @@ -# Contributor Guide - -## Prerequisites - -Install [Poetry](https://github.com/python-poetry/poetry) by following the [official installation instructions](https://github.com/python-poetry/poetry#installation). Optionally (but recommended), configure Poetry to create a virtual environment in a folder named `.venv` within the root directory of the project: - -```bash -poetry config virtualenvs.in-project true -``` - -## Setup - -To create a development environment and install the runtime and development dependencies, run: - -```bash -poetry install -``` - -Then enter the virtual environment created by Poetry: - -```bash -poetry shell -``` - -## Static checks - -The project uses static checks using fantastic [pre-commit](https://pre-commit.com/). Every change is checked on CI and if it does not pass the tests it cannot be accepted. If you want to check locally then run following command to install pre-commit. - -To turn on pre-commit checks for commit operations in git, enter: - -```bash -pre-commit install -``` - -To run all checks on your staged files, enter: - -```bash -pre-commit run -``` - -To run all checks on all files, enter: - -```bash -pre-commit run --all-files -``` - -Pre-commit check results are also attached to your PR through integration with Github Action. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..92394285 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1 @@ +Please read the `Contributing `__ guidelines in the documentation site. diff --git a/README.rst b/README.rst index 8db828ac..3041554b 100644 --- a/README.rst +++ b/README.rst @@ -22,15 +22,14 @@ Openapi-core is a Python library that adds client-side and server-side support for the `OpenAPI v3.0 `__ and `OpenAPI v3.1 `__ specification. + Key features -************ +############ -* **Validation** of requests and responses -* Schema **casting** and **unmarshalling** -* Media type and parameters **deserialization** -* **Security** providers (API keys, Cookie, Basic and Bearer HTTP authentications) -* Custom **deserializers** and **formats** -* **Integration** with libraries and frameworks +* **Validation** and **unmarshalling** of request and response data (including webhooks) +* **Integration** with popular libraries (Requests, Werkzeug) and frameworks (Django, Falcon, Flask, Starlette) +* Customization with media type **deserializers** and format **unmarshallers** +* **Security** data providers (API keys, Cookie, Basic and Bearer HTTP authentications) Documentation @@ -44,19 +43,19 @@ Installation Recommended way (via pip): -:: +.. code-block:: console - $ pip install openapi-core + pip install openapi-core Alternatively you can download the code and install from the repository: -.. code-block:: bash +.. code-block:: console - $ pip install -e git+https://github.com/p1c2u/openapi-core.git#egg=openapi_core + pip install -e git+https://github.com/p1c2u/openapi-core.git#egg=openapi_core -Usage -##### +First steps +########### Firstly create your specification object. @@ -66,98 +65,50 @@ Firstly create your specification object. spec = Spec.from_file_path('openapi.json') -Now you can use it to validate against requests and/or responses. - -Request -******* - -Use ``validate_request`` function to validate request against a given spec. +Now you can use it to validate and unmarshal against requests and/or responses. .. code-block:: python - from openapi_core import validate_request - - # raise error if request is invalid - result = validate_request(request, spec=spec) + from openapi_core import unmarshal_request -Request object should implement OpenAPI Request protocol (See `Integrations `__). + # raises error if request is invalid + result = unmarshal_request(request, spec=spec) -(For OpenAPI v3.1) Use the same function to validate webhook request against a given spec. +Retrieve validated and unmarshalled request data .. code-block:: python - # raise error if request is invalid - result = validate_request(webhook_request, spec=spec) - -Webhook request object should implement OpenAPI WebhookRequest protocol (See `Integrations `__). - -Retrieve request data from validation result - -.. code-block:: python - - # get parameters object with path, query, cookies and headers parameters - validated_params = result.parameters - # or specific parameters - validated_path_params = result.parameters.path - + # get parameters + path_params = result.parameters.path + query_params = result.parameters.query + cookies_params = result.parameters.cookies + headers_params = result.parameters.headers # get body - validated_body = result.body - + body = result.body # get security data - validated_security = result.security - -Response -******** + security = result.security -Use ``validate_response`` function to validate response against a given spec. +Request object should implement OpenAPI Request protocol. Check `Integrations `__ to find oficially supported implementations. -.. code-block:: python +For more details read about `Unmarshalling `__ process. - from openapi_core import validate_response +If you just want to validate your request/response data without unmarshalling, read about `Validation `__ instead. - # raise error if response is invalid - result = validate_response(request, response, spec=spec) -Response object should implement OpenAPI Response protocol (See `Integrations `__). +License +####### -(For OpenAPI v3.1) Use the same function to validate response from webhook request against a given spec. +The project is under the terms of BSD 3-Clause License. -.. code-block:: python - - # raise error if request is invalid - result = validate_response(webhook_request, response, spec=spec) - -Retrieve response data from validation result - -.. code-block:: python - - # get headers - validated_headers = result.headers - - # get data - validated_data = result.data - -In order to explicitly validate a: - -* OpenAPI 3.0 spec, import ``V30RequestValidator`` or ``V30ResponseValidator`` -* OpenAPI 3.1 spec, import ``V31RequestValidator`` or ``V31ResponseValidator`` or ``V31WebhookRequestValidator`` or ``V31WebhookResponseValidator`` - -.. code:: python - - from openapi_core import V31ResponseValidator - - result = validate_response(request, response, spec=spec, cls=V31ResponseValidator) - -You can also explicitly import ``V3RequestValidator`` or ``V3ResponseValidator`` which is a shortcut to the latest v3 release. Related projects ################ -* `bottle-openapi-3 `__ - OpenAPI 3.0 Support for the Bottle Web Framework * `openapi-spec-validator `__ - Python library that validates OpenAPI Specs against the OpenAPI 2.0 (aka Swagger) and OpenAPI 3.0 specification + Python library that validates OpenAPI Specs against the OpenAPI 2.0 (aka Swagger), OpenAPI 3.0 and OpenAPI 3.1 specification. The validator aims to check for full compliance with the Specification. * `openapi-schema-validator `__ - Python library that validates schema against the OpenAPI Schema Specification v3.0. + Python library that validates schema against the OpenAPI Schema Specification v3.0 and OpenAPI Schema Specification v3.1. +* `bottle-openapi-3 `__ + OpenAPI 3.0 Support for the Bottle Web Framework * `pyramid_openapi3 `__ Pyramid addon for OpenAPI3 validation of requests and responses. * `tornado-openapi3 `__ diff --git a/docs/conf.py b/docs/conf.py index 17966195..617eed0e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -66,13 +66,10 @@ # Material theme options (see theme.conf for more information) html_theme_options = { - # Set you GA account ID to enable tracking - # 'google_analytics_account': 'UA-XXXXX', - # Specify a base_url used to generate sitemap.xml. If not - # specified, then no sitemap will be built. - #'base_url': 'https://project.github.io/project', - # Set the color and the accent color - # Set the repo location to get a badge with stats + "analytics": { + "provider": "google", + "property": "G-J6T05Z51NY", + }, "repo_url": "https://github.com/p1c2u/openapi-core/", "repo_name": "openapi-core", "repo_type": "github", diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 00000000..fe58b4d4 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,76 @@ +Contributing +============ + +Firstly, thank you all for taking the time to contribute. + +The following section describes how you can contribute to the openapi-core project on GitHub. + +Reporting bugs +-------------- + +Before you report +^^^^^^^^^^^^^^^^^ + +* Check whether your issue does not already exist in the `Issue tracker `__. +* Make sure it is not a support request or question better suited for `Discussion board `__. + +How to submit a report +^^^^^^^^^^^^^^^^^^^^^^ + +* Include clear title. +* Describe your runtime environment with exact versions you use. +* Describe the exact steps which reproduce the problem, including minimal code snippets. +* Describe the behavior you observed after following the steps, pasting console outputs. +* Describe expected behavior to see and why, including links to documentations. + +Code contribution +----------------- + +Prerequisites +^^^^^^^^^^^^^ + +Install `Poetry `__ by following the `official installation instructions `__. Optionally (but recommended), configure Poetry to create a virtual environment in a folder named ``.venv`` within the root directory of the project: + +.. code-block:: console + + poetry config virtualenvs.in-project true + +Setup +^^^^^ + +To create a development environment and install the runtime and development dependencies, run: + +.. code-block:: console + + poetry install + +Then enter the virtual environment created by Poetry: + +.. code-block:: console + + poetry shell + +Static checks +^^^^^^^^^^^^^ + +The project uses static checks using fantastic `pre-commit `__. Every change is checked on CI and if it does not pass the tests it cannot be accepted. If you want to check locally then run following command to install pre-commit. + +To turn on pre-commit checks for commit operations in git, enter: + +.. code-block:: console + + pre-commit install + +To run all checks on your staged files, enter: + +.. code-block:: console + + pre-commit run + +To run all checks on all files, enter: + +.. code-block:: console + + pre-commit run --all-files + +Pre-commit check results are also attached to your PR through integration with Github Action. diff --git a/docs/customizations.rst b/docs/customizations.rst index 8a5ea64c..d4dd4174 100644 --- a/docs/customizations.rst +++ b/docs/customizations.rst @@ -1,8 +1,8 @@ Customizations ============== -Spec validation ---------------- +Specification validation +------------------------ By default, the provided specification is validated on ``Spec`` object creation time. @@ -62,7 +62,7 @@ Here's how you could add support for a ``usdate`` format that handles dates of t 'usdate': validate_usdate, } - result = validate_response( + validate_response( request, response, spec=spec, extra_format_validators=extra_format_validators, diff --git a/docs/index.rst b/docs/index.rst index 7e9c41a7..caf0a63d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,10 +1,17 @@ -.. openapi-core documentation master file, created by - sphinx-quickstart on Tue Feb 2 17:41:34 2021. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +openapi-core +============ -Welcome to openapi-core's documentation! -======================================== +.. toctree:: + :hidden: + :maxdepth: 2 + + unmarshalling + validation + integrations + customizations + security + extensions + contributing Openapi-core is a Python library that adds client-side and server-side support for the `OpenAPI v3.0 `__ @@ -13,33 +20,76 @@ and `OpenAPI v3.1 ` of request and response data (including webhooks) +* :doc:`Integrations ` with popular libraries (Requests, Werkzeug) and frameworks (Django, Falcon, Flask, Starlette) +* :doc:`Customization ` with **media type deserializers** and **format unmarshallers** +* :doc:`Security ` data providers (API keys, Cookie, Basic and Bearer HTTP authentications) +Installation +------------ -Table of contents ------------------ +Recommended way (via pip): -.. Navigation/TOC +.. code-block:: console -.. toctree:: - :maxdepth: 2 + pip install openapi-core - installation - usage - integrations - customizations - extensions +Alternatively you can download the code and install from the repository: + +.. code-block:: console + + pip install -e git+https://github.com/p1c2u/openapi-core.git#egg=openapi_core + +First steps +----------- + +Firstly create your specification object. + +.. code-block:: python + + from openapi_core import Spec + + spec = Spec.from_file_path('openapi.json') + +Now you can use it to validate and unmarshal your requests and/or responses. + +.. code-block:: python + + from openapi_core import unmarshal_request + + # raises error if request is invalid + result = unmarshal_request(request, spec=spec) + +Retrieve validated and unmarshalled request data + +.. code-block:: python + + # get parameters + path_params = result.parameters.path + query_params = result.parameters.query + cookies_params = result.parameters.cookies + headers_params = result.parameters.headers + # get body + body = result.body + # get security data + security = result.security + +Request object should implement OpenAPI Request protocol. Check :doc:`integrations` to find oficially supported implementations. + +For more details read about :doc:`unmarshalling` process. + +If you just want to validate your request/response data without unmarshalling, read about :doc:`validation` instead. + +License +------- + +The project is under the terms of BSD 3-Clause License. Related projects -================ +---------------- * `openapi-spec-validator `__ - Python library that validates OpenAPI Specs against the OpenAPI 2.0 (aka Swagger) and OpenAPI 3.0.0 specification. The validator aims to check for full compliance with the Specification. + Python library that validates OpenAPI Specs against the OpenAPI 2.0 (aka Swagger), OpenAPI 3.0 and OpenAPI 3.1 specification. The validator aims to check for full compliance with the Specification. * `openapi-schema-validator `__ - Python library that validates schema against the OpenAPI Schema Specification v3.0 which is an extended subset of the JSON Schema Specification Wright Draft 00. + Python library that validates schema against the OpenAPI Schema Specification v3.0 and OpenAPI Schema Specification v3.1. diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index ef7032f1..00000000 --- a/docs/installation.rst +++ /dev/null @@ -1,15 +0,0 @@ -Installation -============ - -Recommended way (via pip): - -.. code-block:: console - - $ pip install openapi-core - -Alternatively you can download the code and install from the repository: - -.. code-block:: console - - $ pip install -e git+https://github.com/p1c2u/openapi-core.git#egg=openapi_core - diff --git a/docs/integrations.rst b/docs/integrations.rst index b6e660c3..5beb7f26 100644 --- a/docs/integrations.rst +++ b/docs/integrations.rst @@ -1,6 +1,8 @@ Integrations ============ +Openapi-core integrates with your popular libraries and frameworks. Each integration offers different levels of integration that help validate and unmarshal your request and response data. + Bottle ------ @@ -30,7 +32,7 @@ Django can be integrated by middleware. Add ``DjangoOpenAPIMiddleware`` to your OPENAPI_SPEC = Spec.from_dict(spec_dict) -After that you have access to validation result object with all validated request data from Django view through request object. +After that you have access to unmarshal result object with all validated request data from Django view through request object. .. code-block:: python @@ -56,21 +58,21 @@ You can use ``DjangoOpenAPIRequest`` as a Django request factory: .. code-block:: python - from openapi_core import validate_request + from openapi_core import unmarshal_request from openapi_core.contrib.django import DjangoOpenAPIRequest openapi_request = DjangoOpenAPIRequest(django_request) - result = validate_request(openapi_request, spec=spec) + result = unmarshal_request(openapi_request, spec=spec) You can use ``DjangoOpenAPIResponse`` as a Django response factory: .. code-block:: python - from openapi_core import validate_response + from openapi_core import unmarshal_response from openapi_core.contrib.django import DjangoOpenAPIResponse openapi_response = DjangoOpenAPIResponse(django_response) - result = validate_response(openapi_request, openapi_response, spec=spec) + result = unmarshal_response(openapi_request, openapi_response, spec=spec) Falcon @@ -115,21 +117,21 @@ You can use ``FalconOpenAPIRequest`` as a Falcon request factory: .. code-block:: python - from openapi_core import validate_request + from openapi_core import unmarshal_request from openapi_core.contrib.falcon import FalconOpenAPIRequest openapi_request = FalconOpenAPIRequest(falcon_request) - result = validate_request(openapi_request, spec=spec) + result = unmarshal_request(openapi_request, spec=spec) You can use ``FalconOpenAPIResponse`` as a Falcon response factory: .. code-block:: python - from openapi_core import validate_response + from openapi_core import unmarshal_response from openapi_core.contrib.falcon import FalconOpenAPIResponse openapi_response = FalconOpenAPIResponse(falcon_response) - result = validate_response(openapi_request, openapi_response, spec=spec) + result = unmarshal_response(openapi_request, openapi_response, spec=spec) Flask @@ -196,11 +198,11 @@ You can use ``FlaskOpenAPIRequest`` as a Flask request factory: .. code-block:: python - from openapi_core import validate_request + from openapi_core import unmarshal_request from openapi_core.contrib.flask import FlaskOpenAPIRequest openapi_request = FlaskOpenAPIRequest(flask_request) - result = validate_request(openapi_request, spec=spec) + result = unmarshal_request(openapi_request, spec=spec) For response factory see `Werkzeug`_ integration. @@ -223,32 +225,32 @@ You can use ``RequestsOpenAPIRequest`` as a Requests request factory: .. code-block:: python - from openapi_core import validate_request + from openapi_core import unmarshal_request from openapi_core.contrib.requests import RequestsOpenAPIRequest openapi_request = RequestsOpenAPIRequest(requests_request) - result = validate_request(openapi_request, spec=spec) + result = unmarshal_request(openapi_request, spec=spec) You can use ``RequestsOpenAPIResponse`` as a Requests response factory: .. code-block:: python - from openapi_core import validate_response + from openapi_core import unmarshal_response from openapi_core.contrib.requests import RequestsOpenAPIResponse openapi_response = RequestsOpenAPIResponse(requests_response) - result = validate_response(openapi_request, openapi_response, spec=spec) + result = unmarshal_response(openapi_request, openapi_response, spec=spec) You can use ``RequestsOpenAPIWebhookRequest`` as a Requests webhook request factory: .. code-block:: python - from openapi_core import validate_request + from openapi_core import unmarshal_request from openapi_core.contrib.requests import RequestsOpenAPIWebhookRequest openapi_webhook_request = RequestsOpenAPIWebhookRequest(requests_request, "my_webhook") - result = validate_request(openapi_webhook_request, spec=spec) + result = unmarshal_request(openapi_webhook_request, spec=spec) Starlette @@ -263,21 +265,21 @@ You can use ``StarletteOpenAPIRequest`` as a Starlette request factory: .. code-block:: python - from openapi_core import validate_request + from openapi_core import unmarshal_request from openapi_core.contrib.starlette import StarletteOpenAPIRequest openapi_request = StarletteOpenAPIRequest(starlette_request) - result = validate_request(openapi_request, spec=spec) + result = unmarshal_request(openapi_request, spec=spec) You can use ``StarletteOpenAPIResponse`` as a Starlette response factory: .. code-block:: python - from openapi_core import validate_response + from openapi_core import unmarshal_response from openapi_core.contrib.starlette import StarletteOpenAPIResponse openapi_response = StarletteOpenAPIResponse(starlette_response) - result = validate_response(openapi_request, openapi_response, spec=spec) + result = unmarshal_response(openapi_request, openapi_response, spec=spec) Tornado @@ -298,18 +300,18 @@ You can use ``WerkzeugOpenAPIRequest`` as a Werkzeug request factory: .. code-block:: python - from openapi_core import validate_request + from openapi_core import unmarshal_request from openapi_core.contrib.werkzeug import WerkzeugOpenAPIRequest openapi_request = WerkzeugOpenAPIRequest(werkzeug_request) - result = validate_request(openapi_request, spec=spec) + result = unmarshal_request(openapi_request, spec=spec) You can use ``WerkzeugOpenAPIResponse`` as a Werkzeug response factory: .. code-block:: python - from openapi_core import validate_response + from openapi_core import unmarshal_response from openapi_core.contrib.werkzeug import WerkzeugOpenAPIResponse openapi_response = WerkzeugOpenAPIResponse(werkzeug_response) - result = validate_response(openapi_request, openapi_response, spec=spec) + result = unmarshal_response(openapi_request, openapi_response, spec=spec) diff --git a/docs/security.rst b/docs/security.rst new file mode 100644 index 00000000..596201a0 --- /dev/null +++ b/docs/security.rst @@ -0,0 +1,36 @@ +Security +======== + +Openapi-core provides you easy access to security data for authentication and authorization process. + +Supported security schemas: + +* http – for Basic and Bearer HTTP authentications schemes +* apiKey – for API keys and cookie authentication + +Here's an example with scheme ``BasicAuth`` and ``ApiKeyAuth`` security schemes: + +.. code-block:: yaml + + security: + - BasicAuth: [] + - ApiKeyAuth: [] + components: + securitySchemes: + BasicAuth: + type: http + scheme: basic + ApiKeyAuth: + type: apiKey + in: header + name: X-API-Key + +Security schemes data are accessible from `security` attribute of `RequestUnmarshalResult` object. + +.. code-block:: python + + # get basic auth decoded credentials + result.security['BasicAuth'] + + # get api key + result.security['ApiKeyAuth'] diff --git a/docs/unmarshalling.rst b/docs/unmarshalling.rst new file mode 100644 index 00000000..27797d24 --- /dev/null +++ b/docs/unmarshalling.rst @@ -0,0 +1,117 @@ +Unmarshalling +============= + +Unmarshalling is the process of converting a primitive schema type of value into a higher-level object based on a ``format`` keyword. All request/response data, that can be described by a schema in OpenAPI specification, can be unmarshalled. + +Unmarshallers firstly validate data against the provided schema (See :doc:`validation`). + +Openapi-core comes with a set of built-in format unmarshallers: + +* ``date`` - converts string into a date object, +* ``date-time`` - converts string into a datetime object, +* ``binary`` - converts string into a byte object, +* ``uuid`` - converts string into an UUID object, +* ``byte`` - decodes Base64-encoded string. + +You can also define your own format unmarshallers (See :doc:`customizations`). + +Request unmarshalling +--------------------- + +Use ``unmarshal_request`` function to validate and unmarshal request data against a given spec. By default, OpenAPI spec version is detected: + +.. code-block:: python + + from openapi_core import unmarshal_request + + # raises error if request is invalid + result = unmarshal_request(request, spec=spec) + +Request object should implement OpenAPI Request protocol (See :doc:`integrations`). + +.. note:: + + Webhooks feature is part of OpenAPI v3.1 only + +Use the same function to validate and unmarshal webhook request data against a given spec. + +.. code-block:: python + + # raises error if request is invalid + result = unmarshal_request(webhook_request, spec=spec) + +Webhook request object should implement OpenAPI WebhookRequest protocol (See :doc:`integrations`). + +Retrieve validated and unmarshalled request data + +.. code-block:: python + + # get parameters + path_params = result.parameters.path + query_params = result.parameters.query + cookies_params = result.parameters.cookies + headers_params = result.parameters.headers + # get body + body = result.body + # get security data + security = result.security + +In order to explicitly validate and unmarshal a: + +* OpenAPI 3.0 spec, import ``V30RequestUnmarshaller`` +* OpenAPI 3.1 spec, import ``V31RequestUnmarshaller`` or ``V31WebhookRequestUnmarshaller`` + +.. code:: python + + from openapi_core import V31RequestUnmarshaller + + result = unmarshal_request(request, response, spec=spec, cls=V31RequestUnmarshaller) + +You can also explicitly import ``V3RequestUnmarshaller`` which is a shortcut to the latest OpenAPI v3 version. + +Response unmarshalling +---------------------- + +Use ``unmarshal_response`` function to validate and unmarshal response data against a given spec. By default, OpenAPI spec version is detected: + +.. code-block:: python + + from openapi_core import unmarshal_response + + # raises error if response is invalid + result = unmarshal_response(request, response, spec=spec) + +Response object should implement OpenAPI Response protocol (See :doc:`integrations`). + +.. note:: + + Webhooks feature is part of OpenAPI v3.1 only + +Use the same function to validate and unmarshal response data from webhook request against a given spec. + +.. code-block:: python + + # raises error if request is invalid + result = unmarshal_response(webhook_request, response, spec=spec) + +Retrieve validated and unmarshalled response data + +.. code-block:: python + + # get headers + headers = result.headers + # get data + data = result.data + +In order to explicitly validate and unmarshal a: + +* OpenAPI 3.0 spec, import ``V30ResponseUnmarshaller`` +* OpenAPI 3.1 spec, import ``V31ResponseUnmarshaller`` or ``V31WebhookResponseUnmarshaller`` + +.. code:: python + + from openapi_core import V31ResponseUnmarshaller + + result = unmarshal_response(request, response, spec=spec, cls=V31ResponseUnmarshaller) + +You can also explicitly import ``V3ResponseUnmarshaller`` which is a shortcut to the latest OpenAPI v3 version. diff --git a/docs/usage.rst b/docs/usage.rst deleted file mode 100644 index 65e3c35f..00000000 --- a/docs/usage.rst +++ /dev/null @@ -1,119 +0,0 @@ -Usage -===== - -Firstly create your specification object. - -.. code-block:: python - - from openapi_core import Spec - - spec = Spec.from_file_path('openapi.json') - -Now you can use it to validate against requests and/or responses. - -Request -------- - -Use ``validate_request`` function to validate request against a given spec. By default, OpenAPI spec version is detected: - -.. code-block:: python - - from openapi_core import validate_request - - # raise error if request is invalid - result = validate_request(request, spec=spec) - -Request object should implement OpenAPI Request protocol (See :doc:`integrations`). - -(For OpenAPI v3.1) Use the same function to validate webhook request against a given spec. - -.. code-block:: python - - # raise error if request is invalid - result = validate_request(webhook_request, spec=spec) - -Webhook request object should implement OpenAPI WebhookRequest protocol (See :doc:`integrations`). - -Retrieve validated and unmarshalled request data from validation result - -.. code-block:: python - - # get parameters object with path, query, cookies and headers parameters - validated_params = result.parameters - # or specific location parameters - validated_path_params = result.parameters.path - - # get body - validated_body = result.body - - # get security data - validated_security = result.security - -Response --------- - -Use ``validate_response`` function to validate response against a given spec. By default, OpenAPI spec version is detected: - -.. code-block:: python - - from openapi_core import validate_response - - # raise error if response is invalid - result = validate_response(request, response, spec=spec) - -Response object should implement OpenAPI Response protocol (See :doc:`integrations`). - -(For OpenAPI v3.1) Use the same function to validate response from webhook request against a given spec. - -.. code-block:: python - - # raise error if request is invalid - result = validate_response(webhook_request, response, spec=spec) - -Retrieve validated and unmarshalled response data from validation result - -.. code-block:: python - - # get headers - validated_headers = result.headers - - # get data - validated_data = result.data - -Security --------- - -openapi-core supports security for authentication and authorization process. Security data for security schemas are accessible from `security` attribute of `RequestValidationResult` object. - -For given security specification: - -.. code-block:: yaml - - security: - - BasicAuth: [] - - ApiKeyAuth: [] - components: - securitySchemes: - BasicAuth: - type: http - scheme: basic - ApiKeyAuth: - type: apiKey - in: header - name: X-API-Key - -you can access your security data the following: - -.. code-block:: python - - # get basic auth decoded credentials - result.security['BasicAuth'] - - # get api key - result.security['ApiKeyAuth'] - -Supported security types: - -* http – for Basic and Bearer HTTP authentications schemes -* apiKey – for API keys and cookie authentication - diff --git a/docs/validation.rst b/docs/validation.rst new file mode 100644 index 00000000..ae562511 --- /dev/null +++ b/docs/validation.rst @@ -0,0 +1,90 @@ +Validation +========== + +Validation is a process to validate request/response data under a given schema defined in OpenAPI specification. + +Additionally, openapi-core uses the ``format`` keyword to check if primitive types conform to defined formats. + +Such valid formats can be forther unmarshalled (See :doc:`unmarshalling`). + +Depends on the OpenAPI version, openapi-core comes with a set of built-in format validators such as: ``date``, ``date-time``, ``binary``, ``uuid`` or ``byte``. + +You can also define your own format validators (See :doc:`customizations`). + +Request validation +------------------ + +Use ``validate_request`` function to validate request data against a given spec. By default, OpenAPI spec version is detected: + +.. code-block:: python + + from openapi_core import validate_request + + # raises error if request is invalid + validate_request(request, spec=spec) + +Request object should implement OpenAPI Request protocol (See :doc:`integrations`). + +.. note:: + + Webhooks feature is part of OpenAPI v3.1 only + +Use the same function to validate webhook request data against a given spec. + +.. code-block:: python + + # raises error if request is invalid + validate_request(webhook_request, spec=spec) + +Webhook request object should implement OpenAPI WebhookRequest protocol (See :doc:`integrations`). + +In order to explicitly validate and unmarshal a: + +* OpenAPI 3.0 spec, import ``V30RequestValidator`` +* OpenAPI 3.1 spec, import ``V31RequestValidator`` or ``V31WebhookRequestValidator`` + +.. code:: python + + from openapi_core import V31RequestValidator + + validate_request(request, response, spec=spec, cls=V31RequestValidator) + +You can also explicitly import ``V3RequestValidator`` which is a shortcut to the latest OpenAPI v3 version. + +Response validation +------------------- + +Use ``validate_response`` function to validate response data against a given spec. By default, OpenAPI spec version is detected: + +.. code-block:: python + + from openapi_core import validate_response + + # raises error if response is invalid + validate_response(request, response, spec=spec) + +Response object should implement OpenAPI Response protocol (See :doc:`integrations`). + +.. note:: + + Webhooks feature is part of OpenAPI v3.1 only + +Use the same function to validate response data from webhook request against a given spec. + +.. code-block:: python + + # raises error if request is invalid + validate_response(webhook_request, response, spec=spec) + +In order to explicitly validate a: + +* OpenAPI 3.0 spec, import ``V30ResponseValidator`` +* OpenAPI 3.1 spec, import ``V31ResponseValidator`` or ``V31WebhookResponseValidator`` + +.. code:: python + + from openapi_core import V31ResponseValidator + + validate_response(request, response, spec=spec, cls=V31ResponseValidator) + +You can also explicitly import ``V3ResponseValidator`` which is a shortcut to the latest OpenAPI v3 version.