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:
-
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-autodocsoperates 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. -
Native Pydantic v2 Support If your project uses modern
pydantic(orsqlmodel), 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. -
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.Requestobject. Your routes remain pureaiohttpasync functions. -
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.