django-asyncdocs 0.1.0

"Swagger for everything Swagger doesn't cover."

Full docs, screenshots, and the source live on GitHub — this page is a plain-markdown version of the same README, since PyPI's renderer doesn't support the layout GitHub does.

Auto-generated, interactive documentation — and a live test console — for AsyncAPI specs: WebSocket, SSE, MQTT, or any other async protocol your Django project describes with one. Install it, point it at a spec file, and get a browsable page with a sidebar of channels, a payload schema reference, and a "Try it out" console that authorizes, connects, and lets you trigger a real server-side effect to watch a frame arrive — all without leaving the page.

Supports both AsyncAPI dialects (2.x and 3.0) through one normalizer, so a spec written either way renders through the exact same templates.

Screenshots

Index — one card per registered spec:

Detail — docs + a live test console:

See it in action (animated): browsing the index and authorizing + connecting.

Features

• Auto-generated docs — point it at an AsyncAPI YAML file, get a full docs page. Nothing to write by hand, nothing to keep in sync manually.
• Both AsyncAPI dialects — 2.x and 3.0 render through the exact same templates via one normalizer, so a spec written either way just works.
• A real test console — authorize, connect, and trigger a server-side action to watch a live frame arrive, without leaving the page.
• Secure by default — every access denial is a 404, never a 403 or login redirect, so an unauthorized visitor can't even confirm a spec exists.
• Multi-tenancy hooks — two extension points (TenantResolver, TenantSpecFilter) for projects that already have real tenant isolation to plug in.

Install

1. Install the package

pip install django-asyncdocs

2. Register it and point it at a spec

# settings.py
INSTALLED_APPS = [..., "asyncdocs"]

ASYNC_DOCS = {
    "SPECS": {
        "my-channel": {
            "path": BASE_DIR / "apps" / "ws" / "asyncapi.yaml",
            "login_url": "/api/v1/auth/login/",
            "actions": {"send_test": "myproject.docs_actions.send_test"},
        },
    },
}

3. Mount the URLs

# urls.py
from django.urls import include, path

urlpatterns = [..., path("asyncdocs/", include("asyncdocs.urls"))]

Never written an AsyncAPI spec before, or don't have one yet? Start at writing-your-first-spec.md — it builds one from nothing.

Already have a spec? getting-started.md covers the rest (staff login, the ENABLED gate, verifying it without a browser).

Documentation

• Getting started
• Writing your first AsyncAPI spec
• Configuration reference
• Writing test actions
• Security
• Multi-tenancy
• FAQ / troubleshooting

How it works

AsyncAPI 2.x vs 3.0, briefly. One normalizer per dialect produces the exact same flat shape regardless of which one a spec is written in — the dialect is recorded once (asyncapi_version) and shown as a badge; nothing downstream branches on it.

Security, briefly. Every access denial (failed staff check, IP allowlist, unknown or tenant-filtered slug) is a 404, never a 403 or a login redirect — so a response never confirms a spec exists to someone who can't see it. The console's token lives in a JS variable for the tab only, never localStorage/sessionStorage/a URL, always masked on screen.

Multi-tenancy, briefly. Ships no working isolation — every staff user sees every spec by default, correct for a single-tenant project. Two hooks (TenantResolver, TenantSpecFilter) let a project that already has real tenant isolation plug it in later as a settings change.

Full details for all three: see the docs.

License

MIT — see LICENSE.