Skip to main content

Minimal OpenAPI asynchronous server application

Project description


PyPI version Python versions Build Coverage Status Documentation Status Downloads

Asynchronous web middleware for aiohttp and serving Rest APIs with OpenAPI v 3 specification and with optional PostgreSql database bindings.

Table of Contents


pip install aio-openapi


Clone the repository and create a virtual environment venv.

Install dependencies by running the install script

make install

To run tests

make test

By default tests are run against a database with the following connection string postgresql+asyncpg://postgres:postgres@localhost:5432/openapi. To use a different DB, create a .env file with a different connection string, for example:



  • Asynchronous web routes with aiohttp
  • Data validation, serialization and unserialization with python dataclasses
  • OpenApi v 3 auto documentation
  • SqlAlchemy expression language
  • Asynchronous DB interaction with asyncpg
  • Migrations with alembic
  • SqlAlchemy tables as python dataclasses
  • Support click command line interface
  • Optional sentry middleware

Web App

To create an openapi RESTful application follow this schema (lets call the file

from import rest

def create_app():
    return rest(
            title='A REST API',

def setup_app(app):
    return app

if __name__ == '__main__':

The create_app function creates the aiohttp server application by invoking the rest function. This function adds the click command in the cli mapping entry and add documentation for routes which support OpenAPI docs. The setup_app function is used to actually setup the custom application, usually by adding middleware, routes, shutdown callbacks, database integration and so forth.

OpenAPI Documentation

The library provide tools for creating OpenAPI v 3 compliant endpoints and auto-document them.

An example from test tests/example directory

from typing import List

from aiohttp import web

from openapi.db.path import SqlApiPath
from openapi.spec import op

routes = web.RouteTableDef()

class TasksPath(SqlApiPath):
    summary: Create and query Tasks
        - name: Task
          description: Task tag description
    table = 'tasks'

    @op(query_schema=TaskOrderableQuery, response_schema=List[Task])
    async def get(self) -> web.Response:
        summary: Retrieve Tasks
        description: Retrieve a list of Tasks
                description: Authenticated tasks
        paginated = await self.get_list()
        return paginated.json_response()

    @op(response_schema=Task, body_schema=TaskAdd)
    async def post(self) -> web.Response:
        summary: Create a Task
        description: Create a new Task
                description: the task was successfully added
                description: Failed validation
        data = await self.create_one()
        return self.json_response(data, status=201)

Database Integration

This library provides integration with asyncpg, an high performant asynchronous connector with PostgreSql database. To add the database extension simply use the get_db function in the applicatiuon setup_app function:

from aiohttp import web

from openapi.db import get_db

def setup_app(app: web.Application) -> None:
    db = get_db(app)
    meta = db.metadata

This will enable database connection and command line tools (most of them from alembic):

python db --help

The database container is available at the db app key:


Environment Variables

Several environment variables are used by the library to support testing and deployment.

  • DATASTORE: PostgreSql connection string (same as SqlAlchemy syntax)
  • DBPOOL_MIN_SIZE: minimum size of database connection pool (default is 10)
  • DBPOOL_MAX_SIZE: maximum size of database connection pool (default is 10)

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aio-openapi-3.0.0.tar.gz (46.2 kB view hashes)

Uploaded source

Built Distribution

aio_openapi-3.0.0-py3-none-any.whl (59.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page