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.

    app.py
    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.

    app.py
    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.

api.py
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:

app.py
from connexion import AsyncApp

app = AsyncApp(__name__, jsonifier=)
app.add_api("openapi.yaml", jsonifier=c)
app.py
from connexion import FlaskApp

app = FlaskApp(__name__, jsonifier=...)
app.add_api("openapi.yaml", jsonifier=...):
app.py
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.