Skip to content

Generator and discovery

from litestar_asyncapi.asyncapi.extractors import (
    extract_channels_plugin_channels,
    extract_sse_channels,
    extract_websocket_channels,
)
from litestar_asyncapi.asyncapi.generator import AsyncAPIGenerator

AsyncAPIPlugin runs the generator and caches its result, so applications rarely call it directly. Use the generator to build a document outside the plugin, and the extractors to inspect what discovery finds.

Generator

litestar_asyncapi.asyncapi.generator.AsyncAPIGenerator

Build AsyncAPI documents from Litestar apps and AsyncAPIConfig.

app: Litestar

Application whose routes and plugins are documented.

config: AsyncAPIConfig

Configuration that supplies metadata, explicit contracts and discovery flags.

build_asyncapi() -> AsyncAPI

Build an AsyncAPI document object.

Returns:

Type Description
AsyncAPI

The generated AsyncAPI document.

build_schema() -> dict[str, Any]

Build a serialized AsyncAPI document dict.

Returns:

Type Description
dict[str, Any]

The generated AsyncAPI document as a dict.

Extractors

Each extractor returns the channels found by one discovery source. The generator merges them, applies explicit contracts and rejects conflicting keys.

litestar_asyncapi.asyncapi.extractors.extract_websocket_channels(app: Litestar, *, schema_generator: AsyncAPISchemaGenerator, config: AsyncAPIConfig | None = None) -> list[DiscoveredChannel]

Extract websocket routes from a Litestar application.

Parameters:

Name Type Description Default
app Litestar

Litestar application.

 required
schema_generator AsyncAPISchemaGenerator

Schema generator used to produce message/parameter schemas.

 required
config AsyncAPIConfig | None

Optional AsyncAPI configuration used to control docstring extraction.

 None

Returns:

Type Description
list[DiscoveredChannel]

A list of discovered channels.

litestar_asyncapi.asyncapi.extractors.extract_sse_channels(app: Litestar, *, schema_generator: AsyncAPISchemaGenerator, config: AsyncAPIConfig | None = None) -> list[DiscoveredChannel]

Describe HTTP routes that return ServerSentEvent as send-only channels.

A route keeps its path as channel key unless a WebSocket route shares the path ({path}:sse) or several methods stream events ({path}:sse:{method}); the address is always the path. Only AsyncAPI decorator metadata is read, since HTTP summary, description and operation_id describe the HTTP operation.

Parameters:

Name Type Description Default
app Litestar

Litestar application.

 required
schema_generator AsyncAPISchemaGenerator

Schema generator shared with the document build.

 required
config AsyncAPIConfig | None

Optional AsyncAPI configuration; include_sse_routes=False disables discovery.

 None

Returns:

Type Description
list[DiscoveredChannel]

A list of discovered channels.

Raises:

Type Description
ImproperlyConfiguredException

If a decorator declares a receive operation on an SSE route.

litestar_asyncapi.asyncapi.extractors.extract_channels_plugin_channels(app: Litestar, *, schema_generator: AsyncAPISchemaGenerator, config: AsyncAPIConfig | None = None) -> list[DiscoveredChannel]

Describe ChannelsPlugin generated sockets and configured topics as send-only channels.

Generated routes keep their path as channel key. Configured topics without a generated fixed-topic route become topic-only channels keyed by the topic name. Topics come from the snapshot the application's AsyncAPIPlugin takes at init. Without that snapshot, plugins that allow arbitrary channels contribute no topic-only channels, since runtime subscriptions share their topic mapping.

Parameters:

Name Type Description Default
app Litestar

Litestar application.

 required
schema_generator AsyncAPISchemaGenerator

Schema generator shared with the document build.

 required
config AsyncAPIConfig | None

Optional AsyncAPI configuration controlling which channels are included.

 None

Returns:

Type Description
list[DiscoveredChannel]

A list of discovered channels.

Raises:

Type Description
ImproperlyConfiguredException

If two ChannelsPlugin instances configure the same topic, or a channel_payloads key names no configured topic while no plugin allows arbitrary channels.

Discovered definitions

The extractors return definitions that add their source and provenance to the contract types.

litestar_asyncapi.asyncapi.datastructures.DiscoveredChannel

Bases: ChannelDefinition

A channel definition with discovery provenance.

source: DiscoverySource

Discovery source, which selects the channel's x-litestar-source marker.

provenance: str

Route, topic or configuration that produced the channel, quoted in conflict errors.

route_identity: object | None

Route that produced the channel, or None for topic-only and configured channels.

litestar_asyncapi.asyncapi.datastructures.DiscoveredOperation

Bases: OperationDefinition

An operation definition with its source route and handler description.

provenance: str

Route and handler that produced the operation, quoted in conflict errors.