aiohttp-autodocs 0.1.0__tar.gz

aiohttp_autodocs-0.1.0/.gitignore

@@ -0,0 +1 @@
+__pycache__/

aiohttp_autodocs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karam El labadie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiohttp_autodocs-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: aiohttp-autodocs
+Version: 0.1.0
+Summary: Auto-discovering OpenAPI documentation for aiohttp.
+Project-URL: Homepage, https://github.com/kappall/aiohttp-autodocs
+Project-URL: Repository, https://github.com/kappall/aiohttp-autodocs
+Project-URL: Bug Tracker, https://github.com/kappall/aiohttp-autodocs/issues
+License: MIT
+License-File: LICENSE
+Keywords: aiohttp,api,documentation,openapi,swagger
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: aiohttp[speedups]>=3.9; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pydantic>=2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == 'pydantic'
+Description-Content-Type: text/markdown
+
+# 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
+
+```bash
+# 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.
+
+```python
+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.
+
+```python
+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`

aiohttp_autodocs-0.1.0/README.md

@@ -0,0 +1,97 @@
+# 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
+
+```bash
+# 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.
+
+```python
+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.
+
+```python
+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`

aiohttp_autodocs-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aiohttp-autodocs"
+version = "0.1.0"
+description = "Auto-discovering OpenAPI documentation for aiohttp."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["aiohttp", "openapi", "swagger", "documentation", "api"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Topic :: Software Development :: Documentation",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "aiohttp>=3.9",
+]
+
+[project.optional-dependencies]
+# Enables model_json_schema() extraction from Pydantic/SQLModel models
+pydantic = [
+    "pydantic>=2.0",
+]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "aiohttp[speedups]>=3.9",
+    "pydantic>=2.0",
+    "mypy>=1.8",
+    "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/kappall/aiohttp-autodocs"
+Repository = "https://github.com/kappall/aiohttp-autodocs"
+"Bug Tracker" = "https://github.com/kappall/aiohttp-autodocs/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aiohttp_autodocs"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

aiohttp_autodocs-0.1.0/src/aiohttp_autodocs/__init__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from .config import OpenAPIConfig
+from .decorator import docs
+from ._builder import build_openapi
+
+__all__ = ["docs", "build_openapi", "OpenAPIConfig"]
+__version__ = "0.1.0"

aiohttp_autodocs-0.1.0/src/aiohttp_autodocs/_builder.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import logging
+
+from aiohttp import web
+
+from .config import OpenAPIConfig
+from .scanner import build_spec
+from .ui import render_swagger_ui
+from ._routes import (
+    SPEC_KEY,
+    HTML_KEY,
+    make_spec_handler,
+    make_ui_handler,
+    make_redirect_handler,
+)
+
+logger = logging.getLogger(__name__)
+
+_INITIALIZED_KEY = "_aiohttp_autodocs_initialized"
+
+
+def build_openapi(
+    app: web.Application,
+    config: OpenAPIConfig,
+    *route_tables: web.RouteTableDef,
+) -> None:
+    """
+    Build the OpenAPI spec from *route_tables* and register /openapi.json
+    and /docs on *app*. Call once in create_app(), after all routes are added.
+
+    When ``config.enabled`` is False this is a no-op — no routes are registered.
+    Raises RuntimeError if called more than once on the same app.
+    """
+    if app.get(_INITIALIZED_KEY):
+        raise RuntimeError(
+            "build_openapi() has already been called on this application. "
+            "It must be called exactly once, after all routes are registered."
+        )
+
+    if not config.enabled:
+        logger.info(
+            "aiohttp-autodocs: documentation is disabled "
+            "(OpenAPIConfig.enabled=False). Skipping."
+        )
+        app[_INITIALIZED_KEY] = True
+        return
+
+    spec_bytes = build_spec(config, list(route_tables))
+    app[SPEC_KEY] = spec_bytes
+    app[_INITIALIZED_KEY] = True
+
+    html = render_swagger_ui(
+        spec_url=config.spec_path,
+        title=config.title,
+        cdn_base=config.swagger_ui_cdn,
+    )
+    app[HTML_KEY] = html
+
+    app.router.add_get(config.spec_path, make_spec_handler())
+    app.router.add_get(config.docs_path, make_ui_handler())
+
+    # Redirect /docs/ to /docs to avoid duplicate content.
+    if not config.docs_path.endswith("/"):
+        app.router.add_get(
+            config.docs_path + "/",
+            make_redirect_handler(config.docs_path),
+        )
+
+    logger.info(
+        "aiohttp-autodocs: docs available at %s  |  spec at %s",
+        config.docs_path,
+        config.spec_path,
+    )

aiohttp_autodocs-0.1.0/src/aiohttp_autodocs/_routes.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+# Internal handlers for /openapi.json and /docs.
+# Registered after spec generation so they never appear in the spec itself.
+
+from aiohttp import web
+
+SPEC_KEY = "_aiohttp_autodocs_spec"
+HTML_KEY = "_aiohttp_autodocs_html"
+
+
+def make_spec_handler(spec_key: str = SPEC_KEY):
+
+    async def openapi_json(request: web.Request) -> web.Response:
+        spec_bytes: bytes = request.app[spec_key]
+        return web.Response(
+            body=spec_bytes,
+            content_type="application/json",
+            charset="utf-8",
+            headers={
+                # Allow Swagger UI to call this from any origin during dev
+                "Access-Control-Allow-Origin": "*",
+                # Encourage browsers to not cache a stale spec
+                "Cache-Control": "no-cache",
+            },
+        )
+
+    return openapi_json
+
+
+def make_ui_handler(html_key: str = HTML_KEY):
+
+    async def swagger_ui(request: web.Request) -> web.Response:
+        html: str = request.app[html_key]
+        return web.Response(
+            text=html,
+            content_type="text/html",
+            charset="utf-8",
+        )
+
+    return swagger_ui
+
+
+def make_redirect_handler(target: str):
+
+    async def redirect(_request: web.Request) -> web.Response:
+        raise web.HTTPMovedPermanently(target)
+
+    return redirect

aiohttp_autodocs-0.1.0/src/aiohttp_autodocs/config.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class OpenAPIConfig:
+    """
+    Configuration for the OpenAPI documentation module.
+
+    Example::
+
+        OpenAPIConfig(
+            title="My API",
+            version="1.0.0",
+            description="desc.",
+            servers=[{"url": "http://localhost:8080", "description": "Dev"}],
+            enabled=True,
+            security_schemes={
+                "BearerAuth": {
+                    "type": "http",
+                    "scheme": "bearer",
+                    "bearerFormat": "JWT",
+                }
+            },
+            tags=[
+                {"name": "Alarms", "description": "Alarm management"},
+            ],
+        )
+    """
+
+    title: str
+    version: str
+    description: str = ""
+    """Markdown description displayed below the title in Swagger UI."""
+
+    contact: dict | None = None
+    """Contact object, e.g. ``{"name": "Support", "email": "api@example.com"}``."""
+
+    license_info: dict | None = None
+    servers: list[dict] = field(default_factory=list)
+    tags: list[dict] = field(default_factory=list)
+    security_schemes: dict = field(default_factory=dict)
+    docs_path: str = "/docs"
+    spec_path: str = "/openapi.json"
+    enabled: bool = True
+    swagger_ui_cdn: str = "https://unpkg.com/swagger-ui-dist@5"
+    openapi_version: str = "3.1.0"
+
+    def __post_init__(self) -> None:
+        if not self.title:
+            raise ValueError("OpenAPIConfig.title must not be empty.")
+        if not self.version:
+            raise ValueError("OpenAPIConfig.version must not be empty.")
+        if not self.docs_path.startswith("/"):
+            raise ValueError("OpenAPIConfig.docs_path must start with '/'.")
+        if not self.spec_path.startswith("/"):
+            raise ValueError("OpenAPIConfig.spec_path must start with '/'.")
+        if self.docs_path == self.spec_path:
+            raise ValueError(
+                "OpenAPIConfig.docs_path and spec_path must be different paths."
+            )

aiohttp_autodocs-0.1.0/src/aiohttp_autodocs/decorator.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+"""
+@docs() : non-invasive decorator for attaching OpenAPI metadata to handlers.
+"""
+
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+#: Attribute name used to store metadata on the handler function.
+#: Prefixed with the package name to avoid collisions with other libraries.
+OPENAPI_META_ATTR = "__aiohttp_autodocs__"
+
+
+def docs(
+    *,
+    summary: str = "",
+    description: str = "",
+    tags: list[str] | None = None,
+    request_body: type | dict | None = None,
+    response: type | dict | None = None,
+    response_list: bool = False,
+    responses: dict[int, type | dict | None] | None = None,
+    query_params: list[tuple[str, ...]] | None = None,
+    path_params: list[tuple[str, ...]] | None = None,
+    security: list[str | dict] | None = None,
+    deprecated: bool = False,
+    include_in_schema: bool = True,
+    operation_id: str | None = None,
+) -> Callable[[F], F]:
+    """
+    Decorator that attaches OpenAPI metadata to an aiohttp route handler.
+
+    **Must be placed ABOVE** the ``@route_table.method()`` decorator so that
+    the metadata is visible on the function object that ends up stored in the
+    route table.
+
+    Example::
+
+        @docs(
+            summary="Create alarm",
+            description="Creates a new alarm and broadcasts it via WebSocket.",
+            tags=["Alarms"],
+            request_body=AlarmCreateSchema,
+            responses={
+                201: Alarm,
+                400: None,
+                500: None,
+            },
+            security=["BearerAuth"],
+        )
+        @alarm_routes.post(f"{PREFIX}/alarms")
+        async def create_alarm(request: web.Request) -> web.Response:
+            ...
+
+    Parameters
+    ----------
+    summary:
+        Short, one-line description shown as the route title in Swagger UI.
+    description:
+        Longer Markdown description shown in the expanded route panel.
+    tags:
+        Tag names used to group routes in the UI, e.g. ``["Alarms"]``.
+    request_body:
+        A Pydantic ``BaseModel`` subclass (or SQLModel) whose
+        ``model_json_schema()`` will be used, **or** a plain dict containing
+        a raw JSON Schema object.
+    response:
+        Shorthand for a single success response model (Pydantic class or
+        dict schema).  The status code defaults to ``200`` for non-POST
+        methods and ``201`` for POST.  Use ``responses`` for multiple codes.
+    response_list:
+        When ``True``, wraps the ``response`` schema in
+        ``{"type": "array", "items": <schema>}``.
+    responses:
+        Fine-grained per-status-code responses.  Keys are HTTP status code
+        integers; values are Pydantic model classes, raw dicts, or ``None``
+        (for responses with no body).  Takes precedence over ``response``.
+    query_params:
+        List of tuples describing query parameters::
+
+            query_params=[
+                ("severity", "string",  "Filter by severity", False),
+                ("limit",    "integer", "Max results",        False),
+            ]
+
+        Each tuple: ``(name, openapi_type, description, required)``.
+        ``description`` and ``required`` are optional (default ``""`` / ``False``).
+    path_params:
+        Explicit path parameter declarations::
+
+            path_params=[("alarm_id", "integer", "The alarm's primary key")]
+
+        Each tuple: ``(name, openapi_type, description)``.
+        If omitted, path params are auto-detected from the route path pattern
+        (``{param_name}``) and typed as ``string``.
+    security:
+        List of security scheme names (strings) or full security requirement
+        objects (dicts).  Names must match keys in
+        :attr:`OpenAPIConfig.security_schemes`::
+
+            security=["BearerAuth"]
+    deprecated:
+        When ``True``, marks the operation as deprecated in the spec.
+    include_in_schema:
+        When ``False``, this route is silently excluded from the spec.
+        Useful for internal or diagnostic routes.
+    operation_id:
+        Explicit ``operationId`` string.  Auto-generated from method + path
+        if not provided (e.g. ``getApiV1AlarmsAlarmId``).
+    """
+
+    def decorator(func: F) -> F:
+        setattr(func, OPENAPI_META_ATTR, {
+            "summary": summary,
+            "description": description,
+            "tags": list(tags) if tags else [],
+            "request_body": request_body,
+            "response": response,
+            "response_list": response_list,
+            "responses": dict(responses) if responses else {},
+            "query_params": list(query_params) if query_params else [],
+            "path_params": list(path_params) if path_params else [],
+            "security": list(security) if security is not None else None,
+            "deprecated": deprecated,
+            "include_in_schema": include_in_schema,
+            "operation_id": operation_id,
+        })
+        return func
+
+    return decorator

aiohttp_autodocs-0.1.0/src/aiohttp_autodocs/scanner.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+
+from aiohttp import web
+
+from .config import OpenAPIConfig
+from .decorator import OPENAPI_META_ATTR
+from .schema import extract_schema
+
+logger = logging.getLogger(__name__)
+
+_PATH_PARAM_RE = re.compile(r"\{(\w+)\}")
+
+_STATUS_DESCRIPTIONS: dict[int, str] = {
+    200: "Success",
+    201: "Created",
+    204: "No content",
+    400: "Bad request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not found",
+    409: "Conflict",
+    422: "Unprocessable entity",
+    500: "Internal server error",
+    503: "Service unavailable",
+}
+
+_ERROR_SCHEMA = {
+    "type": "object",
+    "properties": {"error": {"type": "string"}},
+}
+
+
+def build_spec(config: OpenAPIConfig, route_tables: list[web.RouteTableDef]) -> bytes:
+    """Build a frozen OpenAPI spec from *route_tables* and return UTF-8 JSON bytes."""
+    components_schemas: dict[str, Any] = {}
+    paths: dict[str, Any] = {}
+
+    for route_table in route_tables:
+        for route_def in route_table._items:  # noqa: SLF001
+            _process_route(route_def, paths, components_schemas)
+
+    info: dict[str, Any] = {"title": config.title, "version": config.version}
+    if config.description:
+        info["description"] = config.description
+    if config.contact:
+        info["contact"] = config.contact
+    if config.license_info:
+        info["license"] = config.license_info
+
+    spec: dict[str, Any] = {"openapi": config.openapi_version, "info": info}
+    if config.servers:
+        spec["servers"] = config.servers
+    if config.tags:
+        spec["tags"] = config.tags
+
+    components: dict[str, Any] = {}
+    if config.security_schemes:
+        components["securitySchemes"] = config.security_schemes
+    if components_schemas:
+        components["schemas"] = components_schemas
+    if components:
+        spec["components"] = components
+
+    spec["paths"] = paths
+
+    n_ops = sum(len(ops) for ops in paths.values())
+    logger.info("aiohttp-autodocs: %d operation(s) across %d path(s).", n_ops, len(paths))
+
+    return json.dumps(spec, indent=2, default=str).encode("utf-8")
+
+
+def _process_route(
+    route_def: Any,
+    paths: dict[str, Any],
+    components: dict[str, Any],
+) -> None:
+    handler = route_def.handler
+    meta: dict[str, Any] | None = getattr(handler, OPENAPI_META_ATTR, None)
+
+    if meta is None or not meta.get("include_in_schema", True):
+        return
+
+    path: str = route_def.path
+    method: str = route_def.method.lower()
+
+    if method == "*" or _is_websocket_route(path, handler):
+        return
+
+    operation = _build_operation(meta, method, path, components)
+
+    if path not in paths:
+        paths[path] = {}
+    paths[path][method] = operation
+
+    logger.debug("Registered %s %s → %s", method.upper(), path, handler.__name__)
+
+
+def _build_operation(
+    meta: dict[str, Any],
+    method: str,
+    path: str,
+    components: dict[str, Any],
+) -> dict[str, Any]:
+    op: dict[str, Any] = {}
+
+    if meta["summary"]:
+        op["summary"] = meta["summary"]
+    if meta["description"]:
+        op["description"] = meta["description"]
+    if meta["tags"]:
+        op["tags"] = meta["tags"]
+    if meta["deprecated"]:
+        op["deprecated"] = True
+
+    op["operationId"] = meta.get("operation_id") or _make_operation_id(method, path)
+
+    if meta.get("security") is not None:
+        op["security"] = [
+            {s: []} if isinstance(s, str) else s for s in meta["security"]
+        ]
+
+    parameters = _build_parameters(meta, path)
+    if parameters:
+        op["parameters"] = parameters
+
+    request_body_model = meta.get("request_body")
+    if request_body_model is not None:
+        schema = extract_schema(request_body_model, components)
+        if schema:
+            op["requestBody"] = {
+                "required": True,
+                "content": {"application/json": {"schema": schema}},
+            }
+
+    op["responses"] = _build_responses(meta, method, components)
+    return op
+
+
+def _build_parameters(meta: dict[str, Any], path: str) -> list[dict[str, Any]]:
+    parameters: list[dict[str, Any]] = []
+    declared = {p[0]: p for p in meta.get("path_params", [])}
+
+    for param_name in _PATH_PARAM_RE.findall(path):
+        if param_name in declared:
+            decl = declared[param_name]
+            entry: dict[str, Any] = {
+                "name": decl[0],
+                "in": "path",
+                "required": True,
+                "schema": {"type": decl[1] if len(decl) > 1 else "string"},
+            }
+            if len(decl) > 2 and decl[2]:
+                entry["description"] = decl[2]
+        else:
+            entry = {"name": param_name, "in": "path", "required": True, "schema": {"type": "string"}}
+        parameters.append(entry)
+
+    for qp in meta.get("query_params", []):
+        qp_entry: dict[str, Any] = {
+            "name": qp[0],
+            "in": "query",
+            "required": bool(qp[3]) if len(qp) > 3 else False,
+            "schema": {"type": qp[1] if len(qp) > 1 else "string"},
+        }
+        if len(qp) > 2 and qp[2]:
+            qp_entry["description"] = qp[2]
+        parameters.append(qp_entry)
+
+    return parameters
+
+
+def _build_responses(
+    meta: dict[str, Any],
+    method: str,
+    components: dict[str, Any],
+) -> dict[str, Any]:
+    # Priority: responses dict > response shorthand > bare 200
+    responses: dict[str, Any] = {}
+
+    if meta.get("responses"):
+        for status_code, response_model in meta["responses"].items():
+            desc = _STATUS_DESCRIPTIONS.get(status_code, "Response")
+            if response_model is None:
+                responses[str(status_code)] = {"description": desc}
+            else:
+                schema = extract_schema(response_model, components)
+                responses[str(status_code)] = (
+                    {"description": desc, "content": {"application/json": {"schema": schema}}}
+                    if schema else {"description": desc}
+                )
+    elif meta.get("response") is not None:
+        schema = extract_schema(meta["response"], components)
+        if schema and meta.get("response_list"):
+            schema = {"type": "array", "items": schema}
+        default_code = "201" if method == "post" else "200"
+        responses[default_code] = {
+            "description": "Success",
+            "content": {"application/json": {"schema": schema}},
+        }
+    else:
+        responses["200"] = {"description": "Success"}
+
+    if "500" not in responses:
+        responses["500"] = {
+            "description": "Internal server error",
+            "content": {"application/json": {"schema": _ERROR_SCHEMA}},
+        }
+
+    return responses
+
+
+def _is_websocket_route(path: str, handler: Any) -> bool:
+    if "/ws" in path.lower() or "websocket" in path.lower():
+        return True
+    return_hint = getattr(handler, "__annotations__", {}).get("return")
+    if return_hint is not None:
+        hint_name = getattr(return_hint, "__name__", str(return_hint))
+        if "WebSocket" in hint_name:
+            return True
+    return False
+
+
+def _make_operation_id(method: str, path: str) -> str:
+    clean = re.sub(r"[{}]", "", path)
+    parts = [p for p in re.split(r"[/_\-]+", clean) if p]
+    return method + "".join(p.capitalize() for p in parts)

aiohttp_autodocs-0.1.0/src/aiohttp_autodocs/schema.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+
+try:
+    from pydantic import BaseModel as _PydanticBase
+    _PYDANTIC_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    _PydanticBase = None  # type: ignore[assignment,misc]
+    _PYDANTIC_AVAILABLE = False
+
+
+# Public helpers
+
+def is_pydantic_model(obj: Any) -> bool:
+    if not _PYDANTIC_AVAILABLE or _PydanticBase is None:
+        return False
+    try:
+        return isinstance(obj, type) and issubclass(obj, _PydanticBase)
+    except TypeError:
+        return False
+
+
+def extract_schema(
+    model: type | dict | None,
+    components: dict[str, Any],
+) -> dict[str, Any] | None:
+    """
+    Convert *model* to an OpenAPI schema dict.
+
+    Nested / referenced component schemas are registered in *components*
+    (the ``components/schemas`` section of the spec) as a side effect.
+
+    Parameters
+    ----------
+    model:
+        - ``None`` -> returns ``None`` (no body / no schema).
+        - ``dict`` -> treated as a raw JSON Schema object, returned as-is.
+        - Pydantic ``BaseModel`` subclass -> ``model_json_schema()`` is called
+          and the result is normalised for OpenAPI.
+
+    components:
+        A mutable dict that accumulates component schemas during spec building.
+        Pass the same object for every call within one spec-building session.
+
+    Raises
+    ------
+    TypeError
+        If *model* is not ``None``, a ``dict``, or a Pydantic model class.
+    ImportError
+        If *model* is a Pydantic model class but Pydantic is not installed.
+    """
+    if model is None:
+        return None
+
+    if isinstance(model, dict):
+        # use as-is (deep-copy to prevent accidental mutation)
+        return copy.deepcopy(model)
+
+    if is_pydantic_model(model):
+        return _pydantic_to_schema(model, components)
+
+    if not _PYDANTIC_AVAILABLE and isinstance(model, type):
+        raise ImportError(
+            f"Cannot extract schema from {model!r}: Pydantic is not installed. "
+            "Install it with: pip install aiohttp-autodocs[pydantic]"
+        )
+
+    raise TypeError(
+        f"Cannot extract schema from {model!r}. "
+        "Expected a Pydantic BaseModel subclass (or SQLModel) or a plain dict."
+    )
+
+
+def _pydantic_to_schema(model: type, components: dict[str, Any]) -> dict[str, Any]:
+    """
+    Generate an OpenAPI-compatible ``$ref`` for a Pydantic model, registering
+    the model (and all nested models from ``$defs``) in *components*.
+    """
+    raw: dict[str, Any] = model.model_json_schema()  # type: ignore[attr-defined]
+    defs: dict[str, Any] = raw.pop("$defs", {})
+
+    for def_name, def_schema in defs.items():
+        if def_name not in components:
+            components[def_name] = _fix_refs(def_schema)
+
+    name = model.__name__
+    if name not in components:
+        components[name] = _fix_refs(raw)
+
+    return {"$ref": f"#/components/schemas/{name}"}
+
+
+def _fix_refs(schema: Any) -> Any:
+    """
+    Recursively rewrite Pydantic's internal ``#/$defs/Foo`` references to
+    the OpenAPI-standard ``#/components/schemas/Foo`` form.
+    """
+    if isinstance(schema, dict):
+        return {
+            k: (
+                f"#/components/schemas/{v[len('#/$defs/'):]}"
+                if k == "$ref" and isinstance(v, str) and v.startswith("#/$defs/")
+                else _fix_refs(v)
+            )
+            for k, v in schema.items()
+        }
+    if isinstance(schema, list):
+        return [_fix_refs(item) for item in schema]
+    return schema

aiohttp_autodocs-0.1.0/src/aiohttp_autodocs/ui.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+
+def render_swagger_ui(
+    spec_url: str,
+    title: str = "API Documentation",
+    cdn_base: str = "https://unpkg.com/swagger-ui-dist@5",
+) -> str:
+    # Escape any single quotes or braces that might break the inline JS
+    safe_spec_url = spec_url.replace("'", "\\'")
+    safe_title = title.replace("<", "&lt;").replace(">", "&gt;")
+
+    return f"""\
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{safe_title}</title>
+    <link rel="stylesheet" href="{cdn_base}/swagger-ui.css" crossorigin="anonymous" />
+    <style>
+      *, *::before, *::after {{ box-sizing: border-box; margin: 0; padding: 0; }}
+      html, body {{ height: 100%; margin: 0; padding: 0; }}
+      #swagger-ui .topbar-wrapper .link {{ display: none; /* hide the default Swagger "Explore" link */ }}
+    </style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+
+    <script src="{cdn_base}/swagger-ui-bundle.js" crossorigin="anonymous"></script>
+    <script src="{cdn_base}/swagger-ui-standalone-preset.js" crossorigin="anonymous"></script>
+    <script>
+      window.addEventListener("load", function () {{
+        window.ui = SwaggerUIBundle({{
+          url: "{safe_spec_url}",
+          dom_id: "#swagger-ui",
+          deepLinking: true,
+          tryItOutEnabled: true,
+          persistAuthorization: true,
+          displayRequestDuration: true,
+          filter: true,
+          presets: [
+            SwaggerUIBundle.presets.apis,
+            SwaggerUIStandalonePreset,
+          ],
+          plugins: [SwaggerUIBundle.plugins.DownloadUrl],
+          layout: "StandaloneLayout",
+          defaultModelsExpandDepth: 1,
+          defaultModelExpandDepth: 2,
+          docExpansion: "list",
+        }});
+      }});
+    </script>
+  </body>
+</html>"""