documentation improvements

CONTRIBUTING.rst

@@ -0,0 +1 @@
+Please read the `Contributing <https://openapi-core.readthedocs.io/en/latest/unmarshalling.html>`__ guidelines in the documentation site.

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 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md>`__
 and `OpenAPI v3.1 <https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md>`__ 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 <https://openapi-core.readthedocs.io/en/latest/integrations.html>`__).
+   # 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 <https://openapi-core.readthedocs.io/en/latest/integrations.html>`__).
-
-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 <https://openapi-core.readthedocs.io/en/latest/integrations.html>`__ to find oficially supported implementations.
 
-.. code-block:: python
+For more details read about `Unmarshalling <https://openapi-core.readthedocs.io/en/latest/unmarshalling.html>`__ process.
 
-   from openapi_core import validate_response
+If you just want to validate your request/response data without unmarshalling, read about `Validation <https://openapi-core.readthedocs.io/en/latest/validation.html>`__ instead.
 
-   # raise error if response is invalid
-   result = validate_response(request, response, spec=spec)
 
-Response object should implement OpenAPI Response protocol (See `Integrations <https://openapi-core.readthedocs.io/en/latest/integrations.html>`__).
+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 <https://github.com/cope-systems/bottle-openapi-3>`__
-   OpenAPI 3.0 Support for the Bottle Web Framework
 * `openapi-spec-validator <https://github.com/p1c2u/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 <https://github.com/p1c2u/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 <https://github.com/cope-systems/bottle-openapi-3>`__
+   OpenAPI 3.0 Support for the Bottle Web Framework
 * `pyramid_openapi3 <https://github.com/niteoweb/pyramid_openapi3>`__
    Pyramid addon for OpenAPI3 validation of requests and responses.
 * `tornado-openapi3 <https://github.com/correl/tornado-openapi3>`__

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",

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 <https://github.com/p1c2u/openapi-core/issues>`__.
+* Make sure it is not a support request or question better suited for `Discussion board <https://github.com/p1c2u/openapi-core/discussions>`__.
+
+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 <https://python-poetry.org>`__ by following the `official installation instructions <https://python-poetry.org/docs/#installation>`__. 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 <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:
+
+.. 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.

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,