Repository files navigation

Explore the docs »

Connexion is a modern Python web framework that makes spec-first and api-first development easy.You describe your API in anOpenAPI (orSwagger) specification with as muchdetail as you want and Connexion will guarantee that it works as you specified.

It works either standalone, or in combination with any ASGI or WSGI-compatible framework!

📢 Connexion 3 was recently released! Read about the changes here »

Connexion provides the following functionalitybased on your specification:

• 🚏Automatic route registration, no@route decorators needed
• 🔒Authentication, split from your application logic
• 🔎Request and response validation of headers, parameters, and body
• 📬Parameter parsing and injection, no request object needed
• 📨Response serialization, you can return regular Python objects
• 📺A Swagger UI console with live documentation and ‘try it out’ feature
• 🧩Pluggability, in all dimensions

Connexion alsohelps you write your OpenAPI specification and develop against it by providing a command line interface which lets you test and mock your specification.

   connexion run openapi.yaml

(back to top)

Sponsors help us dedicate time to maintain Connexion. Want to help?

Explore the options »

(back to top)

With Connexion, you write the spec first. Connexion then calls your Pythoncode, handling the mapping from the specification to the code. Thisincentivizes you to write the specification so that all of yourdevelopers can understand what your API does, even before you write asingle line of code.

If multiple teams depend on your APIs, you can use Connexion to easilysend them the documentation of your API. This guarantees that your API willfollow the specification that you wrote. This is a different process fromthe one offered by most frameworks, which generate a specificationafter you've written the code.Some disadvantages of generating specifications based on code is thatthey often end up lacking details or mix your documentation with the implementationlogic of your application.

(back to top)

You can install connexion using pip:

    $ pip install connexion

Connexion provides 'extras' with optional dependencies to unlock additional features:

• swagger-ui: Enables a Swagger UI console for your application.
• uvicorn: Enables to run the your application usingapp.run() fordevelopment instead of using an external ASGI server.
• flask: Enables theFlaskApp to build applications compatible with the Flaskecosystem.

You can install them as follows:

    $ pip install connexion[swagger-ui]    $ pip install connexion[swagger-ui,uvicorn]

(back to top)

Connexion can be used either as a standalone application or as a middleware wrapping an existingASGI (or WSGI) application written using a different framework. The standalone application can bebuilt using either theAsyncApp orFlaskApp.

• TheAsyncApp is a lightweight application with native asynchronous support. Use it if youare starting a new project and have no specific reason to use one of the other options.

  fromconnexionimportAsyncAppapp=AsyncApp(__name__)

• TheFlaskApp leverages theFlask framework, which is useful if you're migrating fromconnexion 2.X or you want to leverage theFlask ecosystem.

  fromconnexionimportFlaskAppapp=FlaskApp(__name__)

• TheConnexionMiddleware can be wrapped around any existing ASGI or WSGI application.Use it if you already have an application written in a different framework and want to addfunctionality provided by connexion

  fromasgi_frameworkimportAppfromconnexionimportConnexionMiddlewareapp=App(__name__)app=ConnexionMiddleware(app)

(back to top)

While you can register individual routes on your application, Connexion really shines when youregister an API defined by an OpenAPI (or Swagger) specification.The operation described in your specification is automatically linked to your Python view function via theoperationId

run.py

defpost_greeting(name:str,greeting:str):# Paramaeters are automatically unpackedreturnf"{greeting}{name}",200# Responses are automatically serializedapp.add_api("openapi.yaml")

openapi.yaml

...paths:/greeting/{name}:post:operationId:run.post_greetingresponses:'200':content:text/plain:schema:type:stringparameters:           -name:namein:pathrequired:trueschema:type:string           -name:greetingin:queryrequired:trueschema:type:string

(back to top)

If you installed connexion usingconnexion[uvicorn], you can run it using therun method. This is only recommended for development:

app.run()

In production, run your application using an ASGI server such asuvicorn. If you defined yourapp in a python module calledrun.py, you can run it as follows:

    $ uvicorn run:app

Or with gunicorn:

    $ gunicorn -k uvicorn.workers.UvicornWorker run:app

Now you're able to run and use Connexion!

See theexamples folder for more examples.

(back to top)

A full changelog is maintained on theGitHub releases page.

(back to top)

We welcome your ideas, issues, and pull requests. Just follow theusual/standard GitHub practices.

For easy development, install connexion using poetry with all extras, andinstall the pre-commit hooks to automatically run black formatting and static analysis checks.

    pip install poetry    poetry install --all-extras    pre-commit install

You can find out more about how Connexion works and where to apply your changes by having a lookat ourarchitecture.

Unless you explicitly state otherwise in advance, any non trivialcontribution intentionally submitted for inclusion in this project by youto the steward of this repository shall be under theterms and conditions of Apache License 2.0 written below, without anyadditional copyright information, terms or conditions.

(back to top)

We'd like to thank all of Connexion's contributors for working on thisproject, Swagger/OpenAPI for their support, and Zalando for originally developing and releasing Connexion.

About the advantages of working spec-first:

• Blog Atlassian
• API guidelines Zalando
• Blog ML6
• Blog Zalando

Tools to help you work spec-first:

• Online swagger editor
• VS Code plugin
• Pycharm plugin