Skip to content

Plugin and configuration

from litestar_asyncapi import AsyncAPIConfig, AsyncAPIPlugin, DocsConfig

Register one AsyncAPIPlugin per application. AsyncAPIConfig holds the document metadata, explicit contracts and discovery switches, and DocsConfig holds the documentation routes. The contract types that AsyncAPIConfig.channels accepts are on the Contracts page.

Plugin

litestar_asyncapi.AsyncAPIPlugin

Bases: InitPluginProtocol

Generate the application's AsyncAPI document and serve its documentation routes.

One instance belongs to one application, and an application accepts one instance.

Parameters:

Name Type Description Default
config AsyncAPIConfig | None

Plugin configuration; defaults to AsyncAPIConfig().

 None

config: AsyncAPIConfig

Return the plugin configuration.

Returns:

Type Description
AsyncAPIConfig

The AsyncAPI configuration instance.

get_asyncapi(app: Litestar) -> AsyncAPI

Return a defensive copy of the application document.

get_asyncapi_schema(app: Litestar) -> dict[str, Any]

Return a defensive copy of the canonical JSON-compatible document.

get_asyncapi_json(app: Litestar) -> bytes

Return immutable canonical JSON bytes for the bound application.

clear_cache() -> None

Clear generated values while retaining ownership of the bound application.

create_docs_router() -> Router

Create a router for serving AsyncAPI documentation and schema files.

Returns:

Type Description
Router

A Litestar router that serves all configured render plugin paths.

Configuration

litestar_asyncapi.AsyncAPIConfig

Configuration for the AsyncAPI plugin.

This configuration class defines the settings for generating AsyncAPI documentation for event-driven APIs.

title: str | None = None

Title of the document; inherited from the application's OpenAPI config when unset, else AsyncAPI.

version: str | None = None

Version of the API; inherited from the application's OpenAPI config when unset, else 1.0.0.

description: str | None = None

Description of the API; inherited from the application's OpenAPI config when unset.

contact: Contact | None = None

Contact information; inherited from the application's OpenAPI config when unset.

license: License | None = None

License of the API; inherited from the application's OpenAPI config when unset.

terms_of_service: str | None = None

URL of the terms of service; inherited from the application's OpenAPI config when unset.

external_docs: ExternalDocumentation | None = None

Additional external documentation; inherited from the application's OpenAPI config when unset.

inherit_openapi: bool = True

Whether to fill unset metadata and security schemes from app.openapi_config.

Tags and security requirements are never inherited.

inherit_openapi_servers: bool = False

Whether absolute app.openapi_config server URLs become WebSocket servers.

http becomes ws and https becomes wss; relative URLs are skipped. Derived servers are named openapi, openapi_2, … and bound only to channels discovered from WebSocket routes, so other channels do not appear to be served by them. Other channels require an explicit nonempty servers list, since an omitted or empty list means all document servers. Requires inherit_openapi.

spec_version: Literal['3.0.0', '3.1.0'] = '3.1.0'

AsyncAPI version of the generated document.

default_content_type: str | None = None

Default content type for messages, if not otherwise specified.

use_handler_docstrings: bool = False

Whether to use handler docstrings for operation descriptions.

create_examples: bool = False

Whether to auto-generate examples for message payloads.

strict_uniqueness: bool = False

Whether to raise an exception on operationId collision instead of suffixing.

include_websocket_routes: bool = True

Whether to include websocket routes discovered from the application.

include_raw_websocket_routes: bool = False

Include uncertain raw socket contracts with a warning when no explicit metadata exists.

include_sse_routes: bool = True

Whether to include HTTP routes returning ServerSentEvent as send-only channels.

include_channels_plugin: bool = True

Whether to include ChannelsPlugin channels (best-effort).

include_channels_plugin_topics: bool = True

Whether configured ChannelsPlugin topics without a generated route become topic-only channels.

Applies only when include_channels_plugin is true.

channel_payloads: Mapping[str, Any] = field(default_factory=dict)

Payload types keyed by ChannelsPlugin topic name.

A typed topic's generated route and topic-only channel use the generated schema with application/json. Keys must name a configured topic unless a ChannelsPlugin allows arbitrary channels, in which case an unlisted key declares a topic. Keys are validated whatever the include flags say; the arbitrary-channel route stays untyped.

channels: list[ChannelDefinition] = field(default_factory=list)

Explicit channel contracts; a definition replaces a discovered channel with the same key.

servers: dict[str, Server | Reference | dict[str, Any]] = field(default_factory=dict)

Server definitions for the AsyncAPI document.

components: Components = field(default_factory=Components)

Reusable components merged into the generated components object.

operation_traits: dict[str, OperationTrait | Reference | dict[str, Any]] = field(default_factory=dict)

Reusable operation traits registered under components.operationTraits.

message_traits: dict[str, MessageTrait | Reference | dict[str, Any]] = field(default_factory=dict)

Reusable message traits registered under components.messageTraits.

use_cache: bool = True

Whether plugin methods should cache built documents for subsequent calls.

docs: DocsConfig = field(default_factory=DocsConfig)

Documentation routes and UI settings.

litestar_asyncapi.DocsConfig

Documentation routes and optional interactive UI settings.

path: str = '/asyncapi'

Path that the documentation router is mounted under; it must not be the application root.

enabled: bool = True

Whether to mount the documentation routes. Plugin methods and the CLI export work either way.

guards: Sequence[Guard] = ()

Litestar guards applied to every documentation route.

dependencies: Dependencies | None = None

Dependencies provided to the documentation router.

renderer: Literal['asyncapi', 'scalar'] = 'asyncapi'

UI served by the default render plugins: the AsyncAPI React component or Scalar.

interactive: bool = False

Whether to add the React WebSocket console at /playground.

yaml: bool = False

Whether to also serve the document as YAML at /asyncapi.yaml and /asyncapi.yml.

render_plugins: list[AsyncAPIRenderPlugin] | None = None

Render plugins that replace the defaults.

A JSON renderer at /asyncapi.json is added when the list has none, and the field holds the resolved list after initialization.