Response Handling¶
When your application returns a response, Connexion provides the following functionality based on your OpenAPI spec:
It automatically translates Python errors into HTTP problem responses (see Exception Handling)
It automatically serializes the response for certain content types
It validates the response body and headers (see Validation)
On this page, we zoom in on the response serialization.
Response Serialization¶
When working with Connexion, you can return ordinary Python types, and connexion will serialize them into a network response.
When working with Connexion, you can return ordinary Python types, and connexion will serialize them into a network response.
When working with Connexion, you can return ordinary Python types, and connexion will serialize them into a network response.
To activate this behavior when using the ConnexionMiddleware
wrapping a third party
application, you can leverage the following decorators provided by Connexion:
FlaskDecorator
: provides automatic parameter injection and response serialization for Flask applications.from connexion import ConnexionMiddleware from connexion.decorators import FlaskDecorator from flask import Flask app = Flask(__name__) app = ConnexionMiddleware(app) app.add_api("openapi.yaml") @app.route("/endpoint") @FlaskDecorator() def endpoint(name): ...
StarletteDecorator
: provides automatic parameter injection and response serialization for Starlette applications.from connexion import ConnexionMiddleware from connexion.decorators import StarletteDecorator from starlette.applications import Starlette from starlette.routing import Route @StarletteDecorator() def endpoint(name): ... app = Starlette(routes=[Route('/endpoint', endpoint)]) app = ConnexionMiddleware(app) app.add_api("openapi.yaml")
For a full example, see our Frameworks example.
The generic connexion.decorators.WSGIDecorator
and
connexion.decorators.ASGIDecorator
unfortunately don’t support response
serialization, but you can extend them to implement your own decorator for a specific
WSGI or ASGI framework respectively.
Note
If you implement a custom decorator, and think it would be valuable for other users, we would appreciate it as a contribution.
def endpoint():
data = "success"
status_code = 200
headers = {"Content-Type": "text/plain"}
return data, status_code, headers
Data¶
If your API returns responses with the application/json
content type, you can return
a simple dict
or list
and Connexion will serialize (json.dumps
) the data for you.
Customizing JSON serialization
Connexion allows you to customize the Jsonifier
used to serialize json data by subclassing the
connexion.jsonifier.Jsonifier
class and passing it when instantiating your app or registering
an API:
from connexion import AsyncApp
app = AsyncApp(__name__, jsonifier=)
app.add_api("openapi.yaml", jsonifier=c)
from connexion import FlaskApp
app = FlaskApp(__name__, jsonifier=...)
app.add_api("openapi.yaml", jsonifier=...):
from asgi_framework import App
from connexion import ConnexionMiddleware
app = App(__name__)
app = ConnexionMiddleware(app, jsonifier=...)
app.add_api("openapi.yaml", jsonifier=...)
Status code¶
If no status code is provided, Connexion will automatically set it as 200
if data is
returned, or as 204
if None
or connexion.datastructures.NoContent
is returned.
Headers¶
The headers can be used to define any response headers to return. If your OpenAPI specification
defines multiple responses with different content types, you can explicitly set the
Content-Type
header to tell Connexion which response to validate against.
If you do not explicitly return a Content-Type
header, Connexion’s behavior depends on the
Responses defined in your OpenAPI spec:
If you have defined a single response content type in your OpenAPI specification, Connexion will automatically set it.
If you have defined multiple response content types in your OpenAPI specification, Connexion will try to infer which one matches your response and set it. If it cannot infer the content type, an error is raised.
If you have not defined a response content type in your OpenAPI specification, Connexion will automatically set it to
application/json
unless you don’t return any data. This is mostly because of backward-compatibility, and can be circumvented easily by defining a response content type in your OpenAPI specification.
Skipping response serialization¶
If your endpoint returns an instance of connexion.lifecycle.ConnexionResponse
, or a
framework-specific response (flask.Response
or starlette.responses.Response
), response
serialization is skipped, and the response is passed directly to the underlying framework.
If your endpoint returns a Response If the endpoint returns a Response object this response will be used as is.