Quick start

This guide gets you from zero to a live AsyncAPI 3.0 docs page in three steps.

1. Annotate your consumer

Use @document_action on methods that handle messages from the client, and @document_event on methods that handle messages pushed to the client from the channel layer.

# myapp/consumers.py
from channels.generic.websocket import AsyncJsonWebsocketConsumer
from channels_spectacular import document_action, document_event
from myapp.serializers import RequestRideSerializer, AcceptOfferSerializer

class DispatchConsumer(AsyncJsonWebsocketConsumer):

    @document_action(
        summary="Request a ride",
        payload=RequestRideSerializer,
        responses={"ride.requested": {"ride_id": "uuid"}},
        tags=["rides"],
    )
    async def handle_request_ride(self, content):
        ...

    @document_action(
        summary="Accept a driver offer",
        payload=AcceptOfferSerializer,
    )
    async def handle_accept_offer(self, content):
        ...

    @document_event(
        "ride.offer",
        summary="Server pushes a fare offer to the rider",
        payload=RideOfferSerializer,
    )
    async def ride_offer(self, event):
        ...

@document_action automatically derives the action name from the method name by removing the handle_ prefix. For example, handle_request_ride becomes "request_ride". If your consumer follows a different naming convention, you can override the generated name with action="my_name".

@document_event always requires the event type as the first positional argument because the method name (ride_offer) would lose the dotted form ("ride.offer").

2. Wire up the URLs

# myapp/urls.py
from django.urls import path
from channels_spectacular.views import AsyncAPIDocView, AsyncAPISpecView
from myapp.consumers import DispatchConsumer

urlpatterns = [
    # HTML viewer
    path("ws-docs/", AsyncAPIDocView.as_view()),
    # Raw YAML spec
    path(
        "ws-docs/asyncapi.yaml",
        AsyncAPISpecView.as_view(
            consumer=DispatchConsumer,
            channel_path="/ws/dispatch/",
        ),
    ),
]

Include these patterns in your root urls.py:

# project/urls.py
urlpatterns = [
    path("api/v1/", include("myapp.urls")),
    ...
]

3. Browse the docs

Start your development server and open:

  • /api/v1/ws-docs/ interactive AsyncAPI viewer powered by React

  • /api/v1/ws-docs/asyncapi.yaml raw AsyncAPI YAML specification

The specification is generated dynamically from your consumer annotations. When you update an action handler, there is no build step or regeneration process required—simply refresh the page to see the changes.

Next steps

  • Configuration - customize the API title, version, and server settings

  • Multi-consumer support - expose multiple consumers with a built-in consumer switcher

  • Export command - export the generated specification for SDK generation, validation, or CI workflows

  • Payload types - detailed reference for DRF serializers, Pydantic models, dataclasses, and dictionary-based payloads