Skip to main content

aiohttp-autodocs

A zero-overhead, non-invasive OpenAPI 3.1.0 documentation generator for aiohttp.

It gives you the beautiful Swagger UI and Pydantic integration of modern frameworks (like FastAPI), but preserves the raw, unhindered speed and stability of bare aiohttp.

Design Philosophy

This package was built with a specific set of architectural goals in mind to ensure it remains safe and performant in production environments:

  1. Absolute Zero Runtime Overhead Many OpenAPI solutions intercept every HTTP request at runtime to perform validation and dependency injection, adding CPU overhead to every API call. aiohttp-autodocs operates entirely at boot time. It builds the OpenAPI spec once, freezes it to raw bytes in memory, and steps out of the way. When a user hits an endpoint, the decorator does absolutely nothing.

  2. Native Pydantic v2 Support If your project uses modern pydantic (or sqlmodel), you shouldn't have to rewrite your schemas into another validation library just to generate documentation. Our package natively understands Pydantic v2 (including nested $defs), while degrading gracefully to raw Python dictionaries if Pydantic isn't installed.

  3. Non-Invasive Architecture We don't force you to use Class-Based Views or wrap your handlers so heavily that you lose access to the raw web.Request object. Your routes remain pure aiohttp async functions.

  4. No YAML-in-Docstrings Older tools rely on writing OpenAPI YAML directly inside your Python function docstrings. This is error-prone, hard to format, and invisible to IDE type-checkers. We use a strongly typed Python decorator (@docs()) so your IDE catches mistakes instantly.

Installation

# If you want Pydantic support
pip install aiohttp-autodocs[pydantic]

# If you only want raw dictionary schemas
pip install aiohttp-autodocs

Quick Start

1. Decorate your routes

The @docs decorator attaches metadata to your handler. It must be placed above the aiohttp route decorator.

from aiohttp import web
from aiohttp_autodocs import docs
from pydantic import BaseModel

class AlarmSchema(BaseModel):
    id: int
    message: str

alarm_routes = web.RouteTableDef()

@docs(
    summary="List all alarms",
    tags=["Alarms"],
    response=AlarmSchema,
    response_list=True,
    security=["BearerAuth"]
)
@alarm_routes.get("/api/v1/alarms")
async def get_alarms(request: web.Request) -> web.Response:
    return web.json_response([{"id": 1, "message": "High CPU"}])

2. Build the spec at startup

In your application factory (e.g., create_app()), call build_openapi after you've added all your routes.

from aiohttp_autodocs import build_openapi, OpenAPIConfig

app = web.Application()
app.add_routes(alarm_routes)

build_openapi(
    app,
    OpenAPIConfig(
        title="My API",
        version="1.0.0",
        enabled=True,
        security_schemes={
            "BearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "JWT",
            }
        }
    ),
    alarm_routes  # Pass all your RouteTableDefs here
)

web.run_app(app)

3. View your docs

Start your server and visit:

  • Interactive Swagger UI: http://localhost:8080/docs
  • Raw OpenAPI JSON: http://localhost:8080/openapi.json

Contributing

Please see CONTRIBUTING.md for development setup (uv), testing, and workflow guidelines.

Metadata

Release files for aiohttp-autodocs 0.1.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiohttp-autodocs 0.1.8
File Size Uploaded Provenance Actions
aiohttp_autodocs-0.1.8.tar.gz 11.4 kB With provenance Details for aiohttp_autodocs-0.1.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiohttp-autodocs 0.1.8
File Interpreter ABI Platform Actions
aiohttp_autodocs-0.1.8-py3-none-any.whl Python 3 none any Details for aiohttp_autodocs-0.1.8-py3-none-any.whl

Total release size: 25.6 kB

Release files / aiohttp_autodocs-0.1.8.tar.gz

Download URL aiohttp_autodocs-0.1.8.tar.gz
Size 11.4 kB
Tags Source
SHA-256 checksum
How to use checksums
effe3bbc2e430421fede9e6a264c4df0a2dfb7c682bece8b8822c6cab0360855
BLAKE2b-256 checksum
How to use checksums
50a3be9bc4f66557982fcb114c3b0938cbb130b75ea15688498992bf6b4039ef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.

Transparency log

Release files / aiohttp_autodocs-0.1.8-py3-none-any.whl

Download URL aiohttp_autodocs-0.1.8-py3-none-any.whl
Size 14.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cb6efd455bb511d41e7c6706f2386cc1c0c0e0c475fc219184219cfe04e46246
BLAKE2b-256 checksum
How to use checksums
f21b10ea705c1f7363596b76b41f4ee68cf6b1b74b775aca844bd5ed52de48d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.

Transparency log

Security for aiohttp-autodocs 0.1.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aiohttp_autodocs-0.1.8.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.8 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page