django-channels-spectacular

Auto-generate interactive AsyncAPI 3.0 docs for your Django Channels WebSocket consumers.

django-channels-spectacular is the missing documentation layer for Django Channels — think of it as drf-spectacular for WebSockets. Annotate your consumer’s action handlers once and get a live, browsable AsyncAPI 3.0 spec served straight from your Django app. No separate tooling, no manual YAML, no drift between code and docs.

What you get out of the box:

• A View serving asyncapi.yaml with a fully valid AsyncAPI 3.0 spec

• A hosted viewer UI with syntax-highlighted message schemas

• An interactive try-it-out WebSocket console for testing from the browser

• Support for @dataclass, Pydantic models, and DRF serializers as message payloads

• Multi-consumer docs with a spec-switcher dropdown

• Query-param jwt, cookie jwt and session-cookie authentication schemes

Tip

Prefer to see it running? A complete chat + notifications project lives in the example/ directory — see Example app.

Table of Contents

Getting started

• Installation
  • Requirements
  • Install
  • Register the app
• Quick start
  • 1. Annotate your consumer
  • 2. Wire up the URLs
  • 3. Browse the docs
  • Next steps
• Example app
  • Run it
  • What to open
  • How it maps to the library
• Configuration
  • Setting static servers
  • Single consumer (per-view overrides)
  • Multiple consumers (merged spec)
  • Multiple consumers (separate specs with switcher dropdown)
  • Priority order

Guides

• Authentication
  • Session authentication
  • Cookie JWT authentication
  • Query parameter authentication
  • Documenting auth in the spec
  • Try-it-out panel
• Multi-consumer support
  • Merged spec
  • Separate specs with switcher dropdown
  • Generator API
• Export command
  • Generator mode from annotated consumers
  • Template mode from a hand-written YAML
  • Flag reference
  • Consuming the spec from a React app
• Payload types
  • None (no schema)
  • dict (raw JSON Schema)
  • @dataclass class
  • DRF Serializer subclass
  • Pydantic BaseModel
• Hand-written YAML support
  • When to use this approach
  • Django template variables
  • Payload title injection
  • Example
• Try-it-out panel
  • Enabling it
  • What it does
  • Auth flow
  • Multi-consumer mode

Reference

• API Reference
  • Decorators
  • AsyncAPIGenerator
  • Views
  • Management command
• Settings reference
  • Full reference
  • Example: production + dev split

Project

• Changelog
• Contributing
• License

License

Provided by Ibukun Olaifa. Licensed under the 3-Clause BSD License.

Indices and tables

• Index

• Module Index

• Search Page