Connexion

3.3.0 · active · verified Mon Apr 06

Connexion is a modern Python web framework that facilitates API-first development using OpenAPI (formerly Swagger) specifications. It automatically handles routing, request validation, authentication, parameter parsing, and response serialization based on your specification. Version 3.3.0 is the latest stable release, offering a modular, ASGI-compatible architecture with support for both Flask (WSGI) and Starlette (ASGI) backends. The library maintains an active release cadence, frequently publishing updates and new features.

Warnings

breaking Connexion 3.x introduced fundamental changes by adopting the ASGI interface, dropping Aiohttp support entirely. This significantly changes how applications are created and run, favoring `AsyncApp` (Starlette-based) for new asynchronous projects and `FlaskApp` (Flask-based) for WSGI compatibility or migration.
Fix: For new projects, use `connexion.AsyncApp` and `pip install connexion[starlette]`. For migrating from 2.x, consider switching to `AsyncApp` or explicitly use `connexion.FlaskApp` and `pip install connexion[flask]`. Review the official migration guide for detailed steps.
breaking The global `connexion.request` object now represents a Starlette `Request` when using `AsyncApp` in Connexion 3.x, instead of a Flask `Request` as in 2.x. This impacts direct access to request attributes and methods.
Fix: Adjust code that directly accesses `connexion.request` attributes to be compatible with Starlette's `Request` object if using `AsyncApp`. If relying on Flask-specific request features, ensure you are using `FlaskApp`.
breaking Python 3.6 support was dropped in Connexion 3.x, and the minimum required Python version is now 3.9.
Fix: Upgrade your Python environment to 3.9 or higher. The current PyPI metadata indicates `>=3.9, <4.0`.
gotcha Connexion 3.x changed how `uri_parser_class` and `jsonifier` are passed. They are now arguments directly to the `App` constructor or `add_api()` method, rather than through an `options` dictionary or by setting attributes on the `Api` object.
Fix: Update your application initialization to pass `uri_parser_class` and `jsonifier` directly as keyword arguments: `app = AsyncApp(__name__, uri_parser_class=MyParser, jsonifier=MyJsonifier)` or `app.add_api('spec.yaml', uri_parser_class=MyParser)`.
gotcha Connexion 3.x no longer attempts to guess a content type for response serialization if multiple content types are defined in the OpenAPI specification for a given response.
Fix: Ensure your API implementation explicitly returns data in the format matching one of the declared content types in your OpenAPI specification, especially for endpoints with multiple `produces` entries.

Install

pip install connexion Base Installation
pip install connexion[flask] With Flask Backend
pip install connexion[starlette] With Starlette (ASGI) Backend
pip install connexion[swagger-ui] With Swagger UI
pip install connexion[uvicorn] With Uvicorn (for development server)

Imports

AsyncApp
```
from connexion import AsyncApp
```
AsyncApp is the recommended standalone application for new ASGI projects in v3+. For Flask-based apps, use FlaskApp.
FlaskApp
```
from connexion import FlaskApp
```
Used for Flask-based (WSGI) applications, especially when migrating from Connexion 2.x.
ConnexionMiddleware
```
from connexion import ConnexionMiddleware
```
Use to wrap an existing ASGI or WSGI application with Connexion's spec-first capabilities.
request
```
from connexion import request
```
The global request object. In v3, this is a Starlette Request when using AsyncApp, unlike Flask Request in v2.x.

Quickstart

This quickstart demonstrates how to create a simple 'Hello World' API using Connexion's `AsyncApp` (ASGI backend). It defines an API using an `openapi.yaml` specification file and links an operation to a Python function. The application can be run using `uvicorn` (e.g., `uvicorn app:app --reload` from the command line, assuming the Python file is named `app.py`). Ensure `openapi.yaml` is in the same directory as `app.py`.

import connexion
from pathlib import Path

# app.py

def get_hello():
    return {"message": "Hello from Connexion!"}, 200

# Create the Connexion app using AsyncApp for ASGI compatibility
# and look for the OpenAPI spec in the current directory.
app = connexion.AsyncApp(__name__, specification_dir='.')

# Add the API defined in openapi.yaml
app.add_api('openapi.yaml')

# To run the application (requires 'pip install connexion[uvicorn]')
# if __name__ == "__main__":
#     import uvicorn
#     uvicorn.run(app, host="0.0.0.0", port=8080)

# For external running (e.g., via command line: uvicorn app:app --reload)
# Define your OpenAPI spec in openapi.yaml in the same directory:
# openapi: 3.0.0
# info:
#   title: Simple Hello API
#   version: 1.0.0
# paths:
#   /hello:
#     get:
#       operationId: app.get_hello  # Links to the get_hello function in app.py
#       responses:
#         '200':
#           description: A greeting
#           content:
#             application/json:
#               schema:
#                 type: object
#                 properties:
#                   message:
#                     type: string

view raw JSON →