API Reference¶

Decorators¶

`document_action`¶

from channels_spectacular import document_action

@document_action(
    summary: str = "",
    description: str = "",
    payload = None,
    responses: dict | None = None,
    tags: list[str] | None = None,
    action: str | None = None,
    deprecated: bool = False,
)

Marks a consumer method as a client → server action.

Parameter	Type	Description
`summary`	`str`	Short human-readable description shown in the viewer sidebar
`description`	`str`	Extended Markdown description
`payload`	see Payload types	Incoming message schema
`responses`	`{event_type: payload}`	Events the server emits in response
`examples`	`list[dict] \| None`	Concrete message examples (see below)
`tags`	`list[str]`	Groups the operation in the sidebar
`action`	`str` \| `None`	Override the inferred action name (`handle_` stripped)
`deprecated`	`bool`	Marks the operation deprecated in the spec

`document_event`¶

from channels_spectacular import document_event

@document_event(
    event_type: str,
    summary: str = "",
    description: str = "",
    payload = None,
    tags: list[str] | None = None,
    deprecated: bool = False,
)

Marks a consumer method as a server → client event handler.

Parameter	Type	Description
`event_type`	`str`	The dotted event type string, e.g. `"ride.offer"`
`summary`	`str`	Short description
`description`	`str`	Extended Markdown description
`payload`	see Payload types	Outbound message schema
`examples`	`list[dict] \| None`	Concrete message examples (see below)
`tags`	`list[str]`	Groups the operation in the viewer
`deprecated`	`bool`	Marks the operation deprecated

Examples format¶

Each entry in the examples list is a dict with:

Key	Required	Description
`name`	no	Short label shown in the viewer (e.g. `"Cash payment"`)
`summary`	no	One-line description of the example
`payload`	yes	Dict of concrete field values

examples=[
    {
        "name": "Cash payment",
        "summary": "Rider pays with cash at destination",
        "payload": {
            "action": "request_ride",
            "pickup_lat": 6.5244,
            "pickup_lng": 3.3792,
            "fare": "1500.00",
            "payment_method": "cash",
        },
    },
    {
        "name": "Card payment",
        "payload": {
            "action": "request_ride",
            "fare": "1800.00",
            "payment_method": "card",
        },
    },
]

Examples are passed through verbatim into the AsyncAPI messages[name].examples field — no validation or transformation is applied.

`AsyncAPIGenerator`¶

from channels_spectacular import AsyncAPIGenerator

# Single consumer
generator = AsyncAPIGenerator(
    consumer_class,
    info: dict | None = None,
    servers: dict | None = None,
    channel_path: str | None = None,
)

# Multiple consumers
generator = AsyncAPIGenerator(
    consumers: list[tuple[type, str]],
    info: dict | None = None,
    servers: dict | None = None,
)

A low-level generator. Use this when you need the spec as a Python object or YAML string outside of a Django request.

Methods¶

Method	Returns	Description
`get_spec()`	`dict`	Full AsyncAPI 3.0 spec as a Python dict
`get_yaml()`	`str`	YAML-serialized spec string

Views¶

`AsyncAPISpecView`¶

GET /ws-docs/asyncapi.yaml

Returns the AsyncAPI spec as application/yaml.

Class attributes (all override CHANNELS_SPECTACULAR_SETTINGS):

Attribute	Type	Description
`consumer`	`type \| None`	Single annotated consumer class
`consumers`	`list[(type, str)] \| None`	Multiple `(consumer, channel_path)` pairs
`info`	`dict \| None`	AsyncAPI `info` object override
`servers`	`dict \| None`	AsyncAPI `servers` block override
`channel_path`	`str \| None`	WebSocket path for the single-consumer case

Either consumer or consumers must be set; passing neither raises ValueError.

`AsyncAPIDocView`¶

GET /ws-docs/

Renders the HTML page hosting the AsyncAPI React viewer.

Class attributes:

Attribute	Type	Description
`spec_url`	`str \| None`	URL of the YAML spec (single-consumer case). Defaults to `<path>/asyncapi.yaml`
`specs`	`list[(label, url)] \| None`	Multi-consumer mode: renders a switcher dropdown. Takes precedence over `spec_url`
`template_name`	`str`	Override to provide a custom HTML template

Management command¶

See Export command for the full export_asyncapi reference.

API Reference¶

Decorators¶

document_action¶

document_event¶