Merge pull request #739 from python-openapi/feature/docs-integrations-restructure-2

Docs integrations restructure

Author: p1c2u

docs/api.rst

@@ -12,7 +12,6 @@ openapi-core
     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>`__

docs/index.rst

@@ -6,21 +6,36 @@ This section describes integration with `aiohttp.web <https://docs.aiohttp.org/e
 Low level
 ---------
 
-You can use ``AIOHTTPOpenAPIWebRequest`` as an aiohttp request factory:
+The integration defines classes useful for low level integration.
+
+Request
+^^^^^^^
+
+Use ``AIOHTTPOpenAPIWebRequest`` to create OpenAPI request from aiohttp.web request:
 
 .. code-block:: python
 
     from openapi_core.contrib.aiohttp import AIOHTTPOpenAPIWebRequest
 
-    request_body = await aiohttp_request.text()
-    openapi_request = AIOHTTPOpenAPIWebRequest(aiohttp_request, body=request_body)
-    result = openapi.unmarshal_request(openapi_request)
+    async def hello(request):
+        request_body = await request.text()
+        openapi_request = AIOHTTPOpenAPIWebRequest(request, body=request_body)
+        openapi.validate_request(openapi_request)
+        return web.Response(text="Hello, world")
+
+Response
+^^^^^^^^
 
-You can use ``AIOHTTPOpenAPIWebRequest`` as an aiohttp response factory:
+Use ``AIOHTTPOpenAPIWebResponse`` to create OpenAPI response from aiohttp.web response:
 
 .. code-block:: python
 
-    from openapi_core.contrib.starlette import AIOHTTPOpenAPIWebRequest
+    from openapi_core.contrib.starlette import AIOHTTPOpenAPIWebResponse
 
-    openapi_response = StarletteOpenAPIResponse(aiohttp_response)
-    result = openapi.unmarshal_response(openapi_request, openapi_response)
+    async def hello(request):
+        request_body = await request.text()
+        response = web.Response(text="Hello, world")
+        openapi_request = AIOHTTPOpenAPIWebRequest(request, body=request_body)
+        openapi_response = AIOHTTPOpenAPIWebResponse(response)
+        result = openapi.unmarshal_response(openapi_request, openapi_response)
+        return response

docs/integrations/aiohttp.rst

@@ -7,7 +7,9 @@ The integration supports Django from version 3.0 and above.
 Middleware
 ----------
 
-Django can be integrated by middleware. Add ``DjangoOpenAPIMiddleware`` to your ``MIDDLEWARE`` list and define ``OPENAPI``.
+Django can be integrated by `middleware <https://docs.djangoproject.com/en/5.0/topics/http/middleware/>`__ to apply OpenAPI validation to your entire application.
+
+Add ``DjangoOpenAPIMiddleware`` to your ``MIDDLEWARE`` list and define ``OPENAPI``.
 
 .. code-block:: python
   :emphasize-lines: 6,9
@@ -22,6 +24,30 @@ Django can be integrated by middleware. Add ``DjangoOpenAPIMiddleware`` to your
 
     OPENAPI = OpenAPI.from_dict(spec_dict)
 
+After that all your requests and responses will be validated.
+
+Also you have access to unmarshal result object with all unmarshalled request data through ``openapi`` attribute of request object.
+
+.. code-block:: python
+
+    from django.views import View
+
+    class MyView(View):
+       def get(self, request):
+           # get parameters object with path, query, cookies and headers parameters
+           unmarshalled_params = request.openapi.parameters
+           # or specific location parameters
+           unmarshalled_path_params = request.openapi.parameters.path
+
+           # get body
+           unmarshalled_body = request.openapi.body
+
+           # get security data
+           unmarshalled_security = request.openapi.security
+
+Response validation
+^^^^^^^^^^^^^^^^^^^
+
 You can skip response validation process: by setting ``OPENAPI_RESPONSE_CLS`` to ``None``
 
 .. code-block:: python
@@ -38,43 +64,38 @@ You can skip response validation process: by setting ``OPENAPI_RESPONSE_CLS`` to
     OPENAPI = OpenAPI.from_dict(spec_dict)
     OPENAPI_RESPONSE_CLS = None
 
-After that you have access to unmarshal result object with all validated request data from Django view through request object.
-
-.. code-block:: python
-
-    from django.views import View
-
-    class MyView(View):
-       def get(self, req):
-           # get parameters object with path, query, cookies and headers parameters
-           validated_params = req.openapi.parameters
-           # or specific location parameters
-           validated_path_params = req.openapi.parameters.path
-
-           # get body
-           validated_body = req.openapi.body
-
-           # get security data
-           validated_security = req.openapi.security
-
 Low level
 ---------
 
-You can use ``DjangoOpenAPIRequest`` as a Django request factory:
+The integration defines classes useful for low level integration.
+
+Request
+^^^^^^^
+
+Use ``DjangoOpenAPIRequest`` to create OpenAPI request from Django request:
 
 .. code-block:: python
 
     from openapi_core.contrib.django import DjangoOpenAPIRequest
 
-    openapi_request = DjangoOpenAPIRequest(django_request)
-    result = openapi.unmarshal_request(openapi_request)
+    class MyView(View):
+       def get(self, request):
+           openapi_request = DjangoOpenAPIRequest(request)
+           openapi.validate_request(openapi_request)
+
+Response
+^^^^^^^^
 
-You can use ``DjangoOpenAPIResponse`` as a Django response factory:
+Use ``DjangoOpenAPIResponse`` to create OpenAPI response from Django response:
 
 .. code-block:: python
 
     from openapi_core.contrib.django import DjangoOpenAPIResponse
 
-    openapi_response = DjangoOpenAPIResponse(django_response)
-    result = openapi.unmarshal_response(openapi_request, openapi_response)
-
+    class MyView(View):
+       def get(self, request):
+           response = JsonResponse({'hello': 'world'})
+           openapi_request = DjangoOpenAPIRequest(request)
+           openapi_response = DjangoOpenAPIResponse(response)
+           openapi.validate_response(openapi_request, openapi_response)
+           return response

docs/integrations/django.rst

@@ -3,44 +3,34 @@ Flask
 
 This section describes integration with `Flask <https://flask.palletsprojects.com>`__ web framework.
 
-Decorator
----------
+View decorator
+--------------
+
+Flask can be integrated by `view decorator <https://flask.palletsprojects.com/en/latest/patterns/viewdecorators/>`__ to apply OpenAPI validation to your application's specific views.
 
-Flask views can be integrated by ``FlaskOpenAPIViewDecorator`` decorator.
+Use ``FlaskOpenAPIViewDecorator`` with OpenAPI object to create the decorator.
 
 .. code-block:: python
   :emphasize-lines: 1,3,6
 
     from openapi_core.contrib.flask.decorators import FlaskOpenAPIViewDecorator
 
-    openapi = FlaskOpenAPIViewDecorator.from_spec(spec)
+    openapi_validated = FlaskOpenAPIViewDecorator(openapi)
 
     @app.route('/home')
-    @openapi
+    @openapi_validated
     def home():
        return "Welcome home"
 
-Additional customization parameters can be passed to the decorator.
-
-.. code-block:: python
-  :emphasize-lines: 5
-
-    from openapi_core.contrib.flask.decorators import FlaskOpenAPIViewDecorator
-
-    openapi = FlaskOpenAPIViewDecorator.from_spec(
-       spec,
-       extra_format_validators=extra_format_validators,
-    )
-
 You can skip response validation process: by setting ``response_cls`` to ``None``
 
 .. code-block:: python
   :emphasize-lines: 5
 
     from openapi_core.contrib.flask.decorators import FlaskOpenAPIViewDecorator
 
-    openapi = FlaskOpenAPIViewDecorator.from_spec(
-       spec,
+    openapi_validated = FlaskOpenAPIViewDecorator(
+       openapi,
        response_cls=None,
     )
 
@@ -50,7 +40,7 @@ If you want to decorate class based view you can use the decorators attribute:
   :emphasize-lines: 2
 
     class MyView(View):
-       decorators = [openapi]
+       decorators = [openapi_validated]
 
        def dispatch_request(self):
            return "Welcome home"

docs/integrations/flask.rst

@@ -6,30 +6,47 @@ This section describes integration with `Requests <https://requests.readthedocs.
 Low level
 ---------
 
-You can use ``RequestsOpenAPIRequest`` as a Requests request factory:
+The integration defines classes useful for low level integration.
+
+Request
+^^^^^^^
+
+Use ``RequestsOpenAPIRequest`` to create OpenAPI request from Requests request:
 
 .. code-block:: python
 
     from openapi_core.contrib.requests import RequestsOpenAPIRequest
 
-    openapi_request = RequestsOpenAPIRequest(requests_request)
-    result = openapi.unmarshal_request(openapi_request)
+    request = Request('POST', url, data=data, headers=headers)
+    openapi_request = RequestsOpenAPIRequest(request)
+    openapi.validate_request(openapi_request)
 
-You can use ``RequestsOpenAPIResponse`` as a Requests response factory:
+Webhook request
+^^^^^^^^^^^^^^^
+
+Use ``RequestsOpenAPIWebhookRequest`` to create OpenAPI webhook request from Requests request:
 
 .. code-block:: python
 
-    from openapi_core.contrib.requests import RequestsOpenAPIResponse
+    from openapi_core.contrib.requests import RequestsOpenAPIWebhookRequest
 
-    openapi_response = RequestsOpenAPIResponse(requests_response)
-    result = openapi.unmarshal_response(openapi_request, openapi_response)
+    request = Request('POST', url, data=data, headers=headers)
+    openapi_webhook_request = RequestsOpenAPIWebhookRequest(request, "my_webhook")
+    openapi.validate_request(openapi_webhook_request)
 
+Response
+^^^^^^^^
 
-You can use ``RequestsOpenAPIWebhookRequest`` as a Requests webhook request factory:
+Use ``RequestsOpenAPIResponse`` to create OpenAPI response from Requests response:
 
 .. code-block:: python
 
-    from openapi_core.contrib.requests import RequestsOpenAPIWebhookRequest
+    from openapi_core.contrib.requests import RequestsOpenAPIResponse
 
-    openapi_webhook_request = RequestsOpenAPIWebhookRequest(requests_request, "my_webhook")
-    result = openapi.unmarshal_request(openapi_webhook_request)
+    session = Session()
+    request = Request('POST', url, data=data, headers=headers)
+    prepped = session.prepare_request(req)
+    response = session,send(prepped)
+    openapi_request = RequestsOpenAPIRequest(request)
+    openapi_response = RequestsOpenAPIResponse(response)
+    openapi.validate_response(openapi_request, openapi_response)

docs/integrations/requests.rst

@@ -6,7 +6,9 @@ This section describes integration with `Starlette <https://www.starlette.io>`__
 Middleware
 ----------
 
-Starlette can be integrated by middleware. Add ``StarletteOpenAPIMiddleware`` with ``spec`` to your ``middleware`` list.
+Starlette can be integrated by `middleware <https://www.starlette.io/middleware/>`__ to apply OpenAPI validation to your entire application.
+
+Add ``StarletteOpenAPIMiddleware`` with OpenAPI object to your ``middleware`` list.
 
 .. code-block:: python
   :emphasize-lines: 1,6
@@ -24,21 +26,26 @@ Starlette can be integrated by middleware. Add ``StarletteOpenAPIMiddleware`` wi
         middleware=middleware,
     )
 
-After that you have access to unmarshal result object with all validated request data from endpoint through ``openapi`` key of request's scope directory.
+After that all your requests and responses will be validated.
+
+Also you have access to unmarshal result object with all unmarshalled request data through ``openapi`` scope of request object.
 
 .. code-block:: python
 
-    async def get_endpoint(req):
+    async def homepage(request):
        # get parameters object with path, query, cookies and headers parameters
-       validated_params = req.scope["openapi"].parameters
+       unmarshalled_params = request.scope["openapi"].parameters
        # or specific location parameters
-       validated_path_params = req.scope["openapi"].parameters.path
+       unmarshalled_path_params = request.scope["openapi"].parameters.path
 
        # get body
-       validated_body = req.scope["openapi"].body
+       unmarshalled_body = request.scope["openapi"].body
 
        # get security data
-       validated_security = req.scope["openapi"].security
+       unmarshalled_security = request.scope["openapi"].security
+
+Response validation
+^^^^^^^^^^^^^^^^^^^
 
 You can skip response validation process: by setting ``response_cls`` to ``None``
 
@@ -57,20 +64,34 @@ You can skip response validation process: by setting ``response_cls`` to ``None`
 Low level
 ---------
 
-You can use ``StarletteOpenAPIRequest`` as a Starlette request factory:
+The integration defines classes useful for low level integration.
+
+Request
+^^^^^^^
+
+Use ``StarletteOpenAPIRequest`` to create OpenAPI request from Starlette request:
 
 .. code-block:: python
 
     from openapi_core.contrib.starlette import StarletteOpenAPIRequest
 
-    openapi_request = StarletteOpenAPIRequest(starlette_request)
-    result = openapi.unmarshal_request(openapi_request)
+    async def homepage(request):
+        openapi_request = StarletteOpenAPIRequest(request)
+        result = openapi.unmarshal_request(openapi_request)
+        return JSONResponse({'hello': 'world'})
+
+Response
+^^^^^^^^
 
-You can use ``StarletteOpenAPIResponse`` as a Starlette response factory:
+Use ``StarletteOpenAPIResponse`` to create OpenAPI response from Starlette response:
 
 .. code-block:: python
 
     from openapi_core.contrib.starlette import StarletteOpenAPIResponse
 
-    openapi_response = StarletteOpenAPIResponse(starlette_response)
-    result = openapi.unmarshal_response(openapi_request, openapi_response)
+    async def homepage(request):
+        response = JSONResponse({'hello': 'world'})
+        openapi_request = StarletteOpenAPIRequest(request)
+        openapi_response = StarletteOpenAPIResponse(response)
+        openapi.validate_response(openapi_request, openapi_response)
+        return response