Routing¶

Connexion leverages your OpenAPI contract to route requests to your python functions. This can be done in two ways:

Explicitly
Automatically

Explicit routing¶

Connexion uses the operation_id to link each operation in your API contract to the python function that should handle it.

openapi.yaml¶

paths:
  /hello_world:
    post:
      operationId: myapp.api.hello_world

Based on the operationId above, any POST request to http://{HOST}/hello_world, will be handled by the hello_world function in the myapp.api module.

Optionally, you can include x-openapi-router-controller or x-swagger-router-controller in your operationId to make your operationId relative:

openapi.yaml¶

paths:
  /hello_world:
    post:
      x-openapi-router-controller: myapp.api
      operationId: hello_world

If all your operations are relative, you can use the RelativeResolver class when registering your API instead of repeating the same x-openapi-router-controller in every operation:

app.py¶

import connexion
from connexion.resolver import RelativeResolver

app = connexion.AsyncApp(__name__)
app.add_api('openapi.yaml', resolver=RelativeResolver('myapp.api'))

Note that HEAD requests will be handled by the operationId specified under the GET operation in the specification. Connexion.request.method can be used to determine which request was made. See ConnexionRequest.

Automatic routing¶

Connexion can also automate the routing for you. You can choose from different Resolvers implementing different resolution strategies.

RestyResolver¶

The RestyResolver will infer an operationId based on the path and HTTP method of each operation in your specification:

app.py¶

import connexion
from connexion.resolver import RestyResolver

app = connexion.FlaskApp(__name__)
app.add_api('openapi.yaml', resolver=RestyResolver('api'))

openapi.yaml¶

paths:
  /:
    get:
       # Implied operationId: api.get
  /foo:
    get:
       # Implied operationId: api.foo.search
    post:
       # Implied operationId: api.foo.post
  /foo/{id}:
    get:
       # Implied operationId: api.foo.get
    put:
       # Implied operationId: api.foo.put
    copy:
       # Implied operationId: api.foo.copy
    delete:
       # Implied operationId: api.foo.delete
  /foo/{id}/bar:
    get:
       # Implied operationId: api.foo.bar.search
  /foo/{id}/bar/{name}:
    get:
       # Implied operationId: api.foo.bar.get

RestyResolver will give precedence to any operationId encountered in the specification and respects x-openapi-router-controller and x-swagger-router-controller.

MethodResolver¶

The MethodResolver works like a RestyResolver, but routes to class methods instead of functions.

app.py¶

import connexion
from connexion.resolver import MethodResolver

app = connexion.FlaskApp(__name__)
app.add_api('openapi.yaml', resolver=MethodResolver('api'))

openapi.yaml¶

paths:
  /foo:
  get:
    # Implied operationId: api.FooView.search
  post:
    # Implied operationId: api.FooView.post
  '/foo/{id}':
  get:
    # Implied operationId: api.FooView.get
  put:
    # Implied operationId: api.FooView.put
  copy:
    # Implied operationId: api.FooView.copy
  delete:
    # Implied operationId: api.FooView.delete

The structure expects a Class to exists inside the api module with the name <<CapitalisedPath>>View.

api.py¶

class PetsView:

  def post(self, body: dict):
    ...

  def put(self, petId, body: dict):
    ...

  def delete(self, petId):
    ...

  def get(self, petId=None):
    ...

  def search(limit=100):
    ...

It is possible to use decorators for the Method view by listing them in the decorator attribute of the class:

api.py¶

def example_decorator(f):

    def decorator(*args, **kwargs):
        return f(*args, **kwargs)

    return decorator

class PetsView:
  """Create Pets service"""

  decorators = [example_decorator]

  ...

Additionally, you may inject dependencies into the class by declaring parameters for this class in the __init__ method and providing the arguments in the MethodViewResolver() call. The arguments are passed down to the class when as_view is called.

A class might look like this:

api.py¶

class PetsView:
    def __init__(self, pets):
        self.pets = pets

And the arguments are provided like this:

app.py¶

MethodViewResolver("api", class_arguments={"PetsView": {"kwargs": {"pets": zoo}}})

MethodResolver will give precedence to any operationId encountered in the specification and respects x-openapi-router-controller and x-swagger-router-controller.

MethodViewResolver¶

The MethodResolver works like a MethodViewResolver, but routes to class methods of a Flask MethodView subclass.

Note

If you migrate from connexion v2 you may want to use the MethodResolver in order to maintain the old behavior. The behavior described here is the new behavior, introduced in connexion v3. Previously, in v2, the MethodViewResolver worked like the MethodResolver in v3.

Another difference is that the MethodResolver will look for search and get methods for collection and single item operations respectively, while MethodViewResolver handles both collection and single item operations via the same get method.

app.py¶

import connexion
from connexion.resolver import MethodResolver

app = connexion.FlaskApp(__name__)
app.add_api('openapi.yaml', resolver=MethodViewResolver('api'))

openapi.yaml¶

paths:
  /foo:
  get:
    # Implied operationId: api.FooView.get
  post:
    # Implied operationId: api.FooView.post
  '/foo/{id}':
  get:
    # Implied operationId: api.FooView.get
  put:
    # Implied operationId: api.FooView.put
  copy:
    # Implied operationId: api.FooView.copy
  delete:
    # Implied operationId: api.FooView.delete

The structure expects a Class to exists inside the api module with the name <<CapitalisedPath>>View.

api.py¶

from flask.views import MethodView


class PetsView(MethodView):

  def post(self, body: dict):
    ...

  def put(self, petId, body: dict):
    ...

  def delete(self, petId):
    ...

  def get(self, petId=None, limit=100):
    ...

Custom resolver¶

You can import and extend connexion.resolver.Resolver to implement your own operationId and function resolution algorithm.

Note

If you implement a custom Resolver, and think it would be valuable for other users, we would appreciate it as a contribution.

Resolver error¶

By default, Connexion strictly enforces the presence of a handler function for any path defined in your specification. Because of this, adding new paths without implementing a corresponding handler function will produce runtime errors and your application will not start. To allow new paths to be added to your specification, e.g. in an API design first workflow, set the resolver_error to configure Connexion to provide an error response for paths that are not yet implemented:

app.py¶

app = connexion.FlaskApp(__name__)
app.add_api('openapi.yaml', resolver_error=501)

Path parameters¶

Path parameters are variable parts of a URL path denoted with curly braces { } in the specification.

OpenAPI 3

openapi.yaml¶

paths:
  /users/{id}:
    parameters:
      - in: path
        name: id   # Note the name is the same as in the path
        required: true
        schema:
          type: integer
        description: The user ID

Swagger 2

swagger.yaml¶

paths:
  /users/{id}:
    parameters:
      - in: path
        name: id   # Note the name is the same as in the path
        required: true
        type: integer
        description: The user ID.

By default this will capture characters up to the end of the path or the next /.

You can use convertors to modify what is captured. The available convertors are:

str returns a string, and is the default.
int returns a Python integer.
float returns a Python float.
path returns the rest of the path, including any additional / characters.

Convertors are used by defining them as the format in the parameter specification

Specify a route parameter’s type as integer or number or its type as string and its format as path to use these converters.

Path parameters are passed as arguments to your python function.

Individual paths¶

You can also add individual paths to your application which are not described in your API contract. This can be useful for eg. /healthz or similar endpoints.

api.py¶

@app.route("/healthz")
def healthz():
    return 200

# Or as alternative to the decorator
app.add_url_rule("/healthz", "healthz", healthz)

AsyncApp

FlaskApp

ConnexionMiddleware

When using the ConnexionMiddleware around an ASGI or WSGI application, you can register individual routes on the wrapped application.

API Versioning and basePath¶

Setting a base path is useful for versioned APIs. An example of a base path would be the 1.0 in http://{HOST}/1.0/hello_world.

OpenAPI 3

If you are using OpenAPI 3, you set your base URL path in the servers block of the specification. You can either specify a full URL, or just a relative path.

openapi.yaml¶

servers:
  - url: https://{{HOST}}/1.0
    description: full url example
  - url: /1.0
    description: relative path example

paths:
  ...

Swagger 2

If you are using Swagger 2.0, you can define a basePath on the top level of your Swagger 2.0 specification.

swagger.yaml¶

basePath: /1.0

paths:
  ...

If you don’t want to include the base path in your specification, you can provide it when adding the API to your application:

app.py¶

app.add_api('openapi.yaml', base_path='/1.0')