Merge pull request #732 from python-openapi/fix/docs-integrations-res…

…tructure

Docs restructure

docs/api.rst

@@ -0,0 +1,5 @@
+API
+===
+
+.. autosummary::
+   :toctree: generated

docs/conf.py

@@ -33,6 +33,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.coverage",

docs/customizations/extra_format_unmarshallers.rst

@@ -0,0 +1,27 @@
+Format unmarshallers
+====================
+
+Based on ``format`` keyword, openapi-core can also unmarshal values to specific formats.
+
+Openapi-core comes with a set of built-in format unmarshallers, but it's also possible to add custom ones.
+
+Here's an example with the ``usdate`` format that converts a value to date object:
+
+.. code-block:: python
+  :emphasize-lines: 11
+
+    from datetime import datetime
+
+    def unmarshal_usdate(value):
+       return datetime.strptime(value, "%m/%d/%y").date
+
+    extra_format_unmarshallers = {
+       'usdate': unmarshal_usdate,
+    }
+
+    config = Config(
+       extra_format_unmarshallers=extra_format_unmarshallers,
+    )
+    openapi = OpenAPI.from_file_path('openapi.json', config=config)
+
+    result = openapi.unmarshal_response(request, response)

docs/customizations/extra_format_validators.rst

@@ -0,0 +1,27 @@
+Format validators
+=================
+
+OpenAPI defines a ``format`` keyword that hints at how a value should be interpreted, e.g. a ``string`` with the type ``date`` should conform to the RFC 3339 date format.
+
+OpenAPI comes with a set of built-in format validators, but it's also possible to add custom ones.
+
+Here's how you could add support for a ``usdate`` format that handles dates of the form MM/DD/YYYY:
+
+.. code-block:: python
+  :emphasize-lines: 11
+
+    import re
+
+    def validate_usdate(value):
+       return bool(re.match(r"^\d{1,2}/\d{1,2}/\d{4}$", value))
+
+    extra_format_validators = {
+       'usdate': validate_usdate,
+    }
+
+    config = Config(
+       extra_format_validators=extra_format_validators,
+    )
+    openapi = OpenAPI.from_file_path('openapi.json', config=config)
+
+    openapi.validate_response(request, response)

docs/customizations/extra_media_type_deserializers.rst

@@ -0,0 +1,25 @@
+Media type deserializers
+========================
+
+OpenAPI comes with a set of built-in media type deserializers such as: ``application/json``, ``application/xml``, ``application/x-www-form-urlencoded`` or ``multipart/form-data``.
+
+You can also define your own ones. Pass custom defined media type deserializers dictionary with supported mimetypes as a key to `unmarshal_response` function:
+
+.. code-block:: python
+  :emphasize-lines: 11
+
+    def protobuf_deserializer(message):
+       feature = route_guide_pb2.Feature()
+       feature.ParseFromString(message)
+       return feature
+
+    extra_media_type_deserializers = {
+       'application/protobuf': protobuf_deserializer,
+    }
+
+    config = Config(
+       extra_media_type_deserializers=extra_media_type_deserializers,
+    )
+    openapi = OpenAPI.from_file_path('openapi.json', config=config)
+
+    result = openapi.unmarshal_response(request, response)

docs/customizations/index.rst

@@ -0,0 +1,16 @@
+Customizations
+==============
+
+OpenAPI accepts ``Config`` object that allows users to customize the behavior validation and unmarshalling processes.
+
+.. toctree::
+    :maxdepth: 1
+
+    spec_validator_cls
+    request_validator_cls
+    response_validator_cls
+    request_unmarshaller_cls
+    response_unmarshaller_cls
+    extra_media_type_deserializers
+    extra_format_validators
+    extra_format_unmarshallers

docs/customizations/request_unmarshaller_cls.rst

@@ -0,0 +1,22 @@
+Request unmarshaller
+====================
+
+By default, request unmarshaller is selected based on detected specification version.
+
+In order to explicitly validate and unmarshal a:
+
+* OpenAPI 3.0 spec, import ``V30RequestUnmarshaller``
+* OpenAPI 3.1 spec, import ``V31RequestUnmarshaller`` or ``V31WebhookRequestUnmarshaller``
+
+.. code-block:: python
+  :emphasize-lines: 1,4
+
+    from openapi_core import V31RequestUnmarshaller
+
+    config = Config(
+       request_unmarshaller_cls=V31RequestUnmarshaller,
+    )
+    openapi = OpenAPI.from_file_path('openapi.json', config=config)
+    result = openapi.unmarshal_request(request)
+
+You can also explicitly import ``V3RequestUnmarshaller`` which is a shortcut to the latest OpenAPI v3 version.

docs/customizations/request_validator_cls.rst

@@ -0,0 +1,22 @@
+Request validator
+=================
+
+By default, request validator is selected based on detected specification version.
+
+In order to explicitly validate a:
+
+* OpenAPI 3.0 spec, import ``V30RequestValidator``
+* OpenAPI 3.1 spec, import ``V31RequestValidator`` or ``V31WebhookRequestValidator``
+
+.. code-block:: python
+  :emphasize-lines: 1,4
+
+    from openapi_core import V31RequestValidator
+
+    config = Config(
+       request_validator_cls=V31RequestValidator,
+    )
+    openapi = OpenAPI.from_file_path('openapi.json', config=config)
+    openapi.validate_request(request)
+
+You can also explicitly import ``V3RequestValidator`` which is a shortcut to the latest OpenAPI v3 version.

docs/customizations/response_unmarshaller_cls.rst

@@ -0,0 +1,20 @@
+Response unmarshaller
+=====================
+
+In order to explicitly validate and unmarshal a:
+
+* OpenAPI 3.0 spec, import ``V30ResponseUnmarshaller`` 
+* OpenAPI 3.1 spec, import ``V31ResponseUnmarshaller`` or ``V31WebhookResponseUnmarshaller`` 
+
+.. code-block:: python
+  :emphasize-lines: 1,4
+
+    from openapi_core import V31ResponseUnmarshaller
+
+    config = Config(
+       response_unmarshaller_cls=V31ResponseUnmarshaller,
+    )
+    openapi = OpenAPI.from_file_path('openapi.json', config=config)
+    result = openapi.unmarshal_response(request, response)
+
+You can also explicitly import ``V3ResponseUnmarshaller``  which is a shortcut to the latest OpenAPI v3 version.

docs/customizations/response_validator_cls.rst

@@ -0,0 +1,22 @@
+Response validator
+==================
+
+By default, response validator is selected based on detected specification version.
+
+In order to explicitly validate a:
+
+* OpenAPI 3.0 spec, import ``V30ResponseValidator`` 
+* OpenAPI 3.1 spec, import ``V31ResponseValidator`` or ``V31WebhookResponseValidator`` 
+
+.. code-block:: python
+  :emphasize-lines: 1,4
+
+    from openapi_core import V31ResponseValidator
+
+    config = Config(
+       response_validator_cls=V31ResponseValidator,
+    )
+    openapi = OpenAPI.from_file_path('openapi.json', config=config)
+    openapi.validate_response(request, response)
+
+You can also explicitly import ``V3ResponseValidator``  which is a shortcut to the latest OpenAPI v3 version.

docs/customizations/spec_validator_cls.rst

@@ -0,0 +1,16 @@
+Specification validation
+========================
+
+By default, on OpenAPI creation time, the provided specification is also validated.
+
+If you know you have a valid specification already, disabling the validator can improve the performance.
+
+.. code-block:: python
+  :emphasize-lines: 1,4,6
+
+    from openapi_core import Config
+
+    config = Config(
+       spec_validator_cls=None,
+    )
+    openapi = OpenAPI.from_file_path('openapi.json', config=config)

docs/extensions.rst

@@ -9,7 +9,7 @@ By default, objects are unmarshalled to dictionaries. You can use dynamically cr
 .. code-block:: yaml
   :emphasize-lines: 5
 
-    ...
+    # ...
     components:
      schemas:
        Coordinates:

docs/index.rst

@@ -3,15 +3,16 @@ openapi-core
 
 .. toctree::
     :hidden:
-    :maxdepth: 2
+    :maxdepth: 3
 
     unmarshalling
     validation
-    integrations
-    customizations
+    integrations/index
+    customizations/index
     security
     extensions
     contributing
+    api
 
 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>`__
@@ -21,8 +22,8 @@ Key features
 ------------
 
 * :doc:`validation` and :doc:`unmarshalling <unmarshalling>` of request and response data (including webhooks)
-* :doc:`Integrations <integrations>` with popular libraries (Requests, Werkzeug) and frameworks (Django, Falcon, Flask, Starlette)
-* :doc:`Customization <customizations>` with **media type deserializers** and **format unmarshallers**
+* :doc:`Integrations <integrations/index>` with popular libraries (Requests, Werkzeug) and frameworks (Django, Falcon, Flask, Starlette)
+* :doc:`Customization <customizations/index>` with **media type deserializers** and **format unmarshallers**
 * :doc:`Security <security>` data providers (API keys, Cookie, Basic and Bearer HTTP authentications)
 
 Installation
@@ -74,7 +75,7 @@ Retrieve validated and unmarshalled request data
     # get security data
     security = result.security
 
-Request object should implement OpenAPI Request protocol. Check :doc:`integrations` to find oficially supported implementations.
+Request object should implement OpenAPI Request protocol. Check :doc:`integrations/index` to find oficially supported implementations.
 
 For more details read about :doc:`unmarshalling` process.