Skip to content

falcon.md

Latest commit

 

History

History
109 lines (78 loc) · 2.93 KB

falcon.md

File metadata and controls

109 lines (78 loc) · 2.93 KB

Falcon

This section describes the integration with the Falcon web framework. The integration supports Falcon version 4.

!!! warning

This integration does not support multipart form body requests.

Middleware

The Falcon API can be integrated using the FalconOpenAPIMiddleware middleware. For explicit transport classes, use FalconWSGIOpenAPIMiddleware for falcon.App and FalconASGIOpenAPIMiddleware for falcon.asgi.App.

from openapi_core.contrib.falcon.middlewares import FalconWSGIOpenAPIMiddleware

openapi_middleware = FalconWSGIOpenAPIMiddleware.from_spec(spec)

app = falcon.App(
    # ...
    middleware=[openapi_middleware],
)

FalconOpenAPIMiddleware supports both WSGI and ASGI Falcon apps. For an explicit ASGI middleware class name, use FalconASGIOpenAPIMiddleware.

from openapi_core.contrib.falcon.middlewares import FalconASGIOpenAPIMiddleware

openapi_middleware = FalconASGIOpenAPIMiddleware.from_spec(spec)

app = falcon.asgi.App(
    # ...
    middleware=[openapi_middleware],
)

Additional customization parameters can be passed to the middleware.

from openapi_core.contrib.falcon.middlewares import FalconOpenAPIMiddleware

openapi_middleware = FalconOpenAPIMiddleware.from_spec(
    spec,
    extra_format_validators=extra_format_validators,
)

app = falcon.App(
    # ...
    middleware=[openapi_middleware],
)

You can skip the response validation process by setting response_cls to None.

from openapi_core.contrib.falcon.middlewares import FalconOpenAPIMiddleware

openapi_middleware = FalconOpenAPIMiddleware.from_spec(
    spec,
    response_cls=None,
)

app = falcon.App(
    # ...
    middleware=[openapi_middleware],
)

After that, you will have access to the validation result object with all validated request data from the Falcon view through the request context.

class ThingsResource:
    def on_get(self, req, resp):
        # Get the parameters object with path, query, cookies, and headers parameters
        validated_params = req.context.openapi.parameters
        # Or specific location parameters
        validated_path_params = req.context.openapi.parameters.path

        # Get the body
        validated_body = req.context.openapi.body

        # Get security data
        validated_security = req.context.openapi.security

Low level

You can use FalconOpenAPIRequest as a Falcon request factory:

from openapi_core.contrib.falcon import FalconOpenAPIRequest

openapi_request = FalconOpenAPIRequest(falcon_request)
result = openapi.unmarshal_request(openapi_request)

You can use FalconOpenAPIResponse as a Falcon response factory:

from openapi_core.contrib.falcon import FalconOpenAPIResponse

openapi_response = FalconOpenAPIResponse(falcon_response)
result = openapi.unmarshal_response(openapi_request, openapi_response)