connexion

Introduction to the Connexion Project

Connexion is an advanced Python web framework that simplifies spec-first and API-first development. At the heart of Connexion lies the philosophy of writing the API specification before diving into coding. This approach ensures that the API's functionality is clearly understood by all stakeholders from the outset.

Key Features

Connexion stands out with an array of features that revolve around your API specification:

• Automatic Route Registration: Say goodbye to the manual @route decorators; Connexion handles route registration for you.
• Authentication: Implements authentication seamlessly, separating it from your application logic.
• Request and Response Validation: Ensures that headers, parameters, and bodies adhere to your specifications.
• Parameter Parsing and Injection: Streamlines the process by negating the need for a request object, enabling direct parameter usage in functions.
• Response Serialization: Allows you to return simple Python objects, which Connexion serializes into the required format.
• Swagger UI: Provides a built-in console with live API documentation, including a "try it out" feature.
• Pluggability: Designed for extension in multiple dimensions, making Connexion adaptable to various needs.

Why Choose Connexion?

The spec-first approach with Connexion facilitates collaboration among developers by ensuring API behavior is transparent and documented from the start. With Connexion, you generate your API documentation based on a pre-written specification, unlike other frameworks that attempt to derive a specification from pre-existing code. This method mitigates common pitfalls such as incomplete documentation or tight coupling of documentation with implementation logic. If your APIs serve multiple teams, Connexion allows you to effortlessly distribute precise API documentation.

How to Use Connexion

Installation

Installation is straightforward using pip:

$ pip install connexion

To unlock additional capabilities, you can install dependencies for features like Swagger UI or integrating with the Flask ecosystem:

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

Creating Your Application

Connexion can be utilized as either a standalone application or integrated with other ASGI or WSGI-compatible applications:

• AsyncApp: Ideal for new projects requiring asynchronous support.

  from connexion import AsyncApp
  app = AsyncApp(__name__)
  

• FlaskApp: Perfect for those leveraging Flask or migrating from Connexion 2.X.

  from connexion import FlaskApp
  app = FlaskApp(__name__)
  

• ConnexionMiddleware: Enables integration with pre-existing ASGI or WSGI applications.

  from asgi_framework import App
  from connexion import ConnexionMiddleware
  app = App(__name__)
  app = ConnexionMiddleware(app)
  

Registering an API

Connexion excels when you register an API using an OpenAPI or Swagger specification. Each operation is mapped to a Python function via operationId.

Example Python Function:

def post_greeting(name: str, greeting: str):
    return f"{greeting} {name}", 200

app.add_api("openapi.yaml")

Example OpenAPI Specification (openapi.yaml):

paths:
  /greeting/{name}:
    post:
      operationId: run.post_greeting
      responses:
        200:
          content:
            text/plain:
              schema:
                type: string
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
        - name: greeting
          in: query
          required: true
          schema:
            type: string

Running Your Application

For development, run your Connexion application easily with:

app.run()

For production, leverage an ASGI server such as uvicorn:

$ uvicorn run:app

or use gunicorn:

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

Community and Contributions

Connexion invites contributions from developers worldwide. Whether through ideas, bug reports, or code, all efforts help to refine and advance the project. To start contributing, utilize poetry for installation with all extras for a smooth development experience.

Conclusion

Connexion presents a strong, flexible option for developers keen on a spec-first approach. It brings uniformity, reduces intervention errors, and ensures robust API documentation and behavior. With strong community support and continuous enhancements, Connexion remains a leading choice for developers seeking a comprehensive framework to build APIs.