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

Docs restructure

Author: p1c2u

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.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_unmarshallers.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_format_validators.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/extra_media_type_deserializers.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/index.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_unmarshaller_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/request_validator_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.