Skip to content

Document

from litestar_asyncapi.spec import AsyncAPI, Components, Info, Reference, Server

AsyncAPIPlugin.get_asyncapi returns an AsyncAPI object. Every model on these pages subclasses BaseSchemaObject, which is documented once below.

Root document

litestar_asyncapi.spec.AsyncAPI

Bases: BaseSchemaObject

AsyncAPI root document.

info: Info

Metadata about the API.

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

AsyncAPI specification version of the document.

id: str | None = None

Identifier of the application the document describes, as a URI.

default_content_type: str | None = None

Media type used by messages that declare none.

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

Servers keyed by name.

channels: dict[str, Channel | Reference] = field(default_factory=dict)

Channels keyed by channel key.

operations: dict[str, Operation | Reference] = field(default_factory=dict)

Operations keyed by operation id.

components: Components = field(default_factory=Components)

Reusable objects that the document references.

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

Specification extensions; every key must start with x-.

litestar_asyncapi.spec.Components

Bases: BaseSchemaObject

AsyncAPI reusable components container.

schemas: dict[str, Schema | Reference | MultiFormatSchema | bool | dict[str, Any]] = field(default_factory=dict)

Reusable payload and header schemas.

messages: dict[str, Message | Reference] = field(default_factory=dict)

Reusable messages.

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

Reusable message traits.

security_schemes: dict[str, SecurityScheme | Reference] = field(default_factory=dict)

Reusable security schemes.

parameters: dict[str, Parameter | Reference] = field(default_factory=dict)

Reusable channel parameters.

correlation_ids: dict[str, CorrelationId | Reference] = field(default_factory=dict)

Reusable correlation ids.

operations: dict[str, Operation | Reference] = field(default_factory=dict)

Reusable operations.

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

Reusable operation traits.

channels: dict[str, Channel | Reference] = field(default_factory=dict)

Reusable channels.

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

Reusable servers.

replies: dict[str, Reply | Reference] = field(default_factory=dict)

Reusable replies.

reply_addresses: dict[str, ReplyAddress | Reference] = field(default_factory=dict)

Reusable reply addresses.

server_variables: dict[str, ServerVariable | Reference] = field(default_factory=dict)

Reusable server variables.

tags: dict[str, Tag | Reference] = field(default_factory=dict)

Reusable tags.

external_docs: dict[str, ExternalDocumentation | Reference] = field(default_factory=dict)

Reusable external documentation objects.

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

Reusable server bindings.

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

Reusable channel bindings.

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

Reusable operation bindings.

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

Reusable message bindings.

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

Specification extensions; every key must start with x-.

litestar_asyncapi.spec.Reference

Bases: BaseSchemaObject

A JSON reference ($ref) wrapper used throughout the spec.

ref: str

JSON pointer or URI of the referenced object, serialized as $ref.

litestar_asyncapi.spec.base.BaseSchemaObject

Base class for AsyncAPI spec objects.

to_schema() -> dict[str, Any]

Serialize the object to a JSON/YAML ready dictionary.

Serialization rules: - omit absent optional fields while preserving explicit nullable literals - normalize keys to AsyncAPI/JSON Schema conventions (camelCase, $ref, etc.) - serialize nested spec objects recursively

Returns:

Type Description
dict[str, Any]

A dictionary representation of the object.

Raises:

Type Description
TypeError

If a field declares an invalid alias metadata value.
ValueError

If an extension key is not prefixed with x-.

Info

litestar_asyncapi.spec.Info

Bases: BaseSchemaObject

Information about the exposed API.

title: str

Title of the application.

version: str

Version of the application API, not of the AsyncAPI specification.

description: str | None = None

Description of the application; CommonMark is allowed.

terms_of_service: str | None = None

URL of the terms of service.

contact: Contact | None = None

Contact information for the API.

license: License | None = None

License of the API.

tags: list[Tag | Reference] | None = None

Tags for logical grouping.

external_docs: ExternalDocumentation | Reference | None = None

Additional external documentation.

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

Specification extensions; every key must start with x-.

litestar_asyncapi.spec.Contact

Bases: BaseSchemaObject

Contact information for the exposed API.

name: str | None = None

Name of the contact person or organization.

url: str | None = None

URL with contact information.

email: str | None = None

Email address of the contact.

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

Specification extensions; every key must start with x-.

litestar_asyncapi.spec.License

Bases: BaseSchemaObject

License information for the exposed API.

name: str

Name of the license.

url: str | None = None

URL of the license text.

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

Specification extensions; every key must start with x-.

litestar_asyncapi.spec.Tag

Bases: BaseSchemaObject

AsyncAPI Tag object.

name: str

Name of the tag.

description: str | None = None

Description of the tag; CommonMark is allowed.

external_docs: ExternalDocumentation | Reference | None = None

Additional external documentation.

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

Specification extensions; every key must start with x-.

litestar_asyncapi.spec.ExternalDocumentation

Bases: BaseSchemaObject

Reference external documentation.

url: str

URL of the documentation.

description: str | None = None

Description of the documentation; CommonMark is allowed.

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

Specification extensions; every key must start with x-.

Servers

litestar_asyncapi.spec.Server

Bases: BaseSchemaObject

AsyncAPI Server object.

host: str

Host name, which may include a port and {variable} expressions.

protocol: str

Protocol used to connect, such as ws, wss or kafka.

title: str | None = None

Human-friendly server title.

summary: str | None = None

Short summary of the server.

protocol_version: str | None = None

Version of the protocol.

pathname: str | None = None

Path relative to the host, which may include {variable} expressions.

description: str | None = None

Description of the server; CommonMark is allowed.

variables: dict[str, ServerVariable | Reference] | None = None

Variables for expressions in host and pathname.

security: list[SecurityScheme | Reference] | None = None

Security schemes that apply to connections to the server.

tags: list[Tag | Reference] | None = None

Tags for logical grouping.

external_docs: ExternalDocumentation | Reference | None = None

Additional external documentation.

bindings: dict[str, Any] | Reference | None = None

Protocol-specific server bindings.

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

Specification extensions; every key must start with x-.

litestar_asyncapi.spec.ServerVariable

Bases: BaseSchemaObject

Server variable for templated server URLs/hosts.

default: str | None = None

Value used when none is supplied.

enum: list[str] | None = None

Allowed values of the variable.

description: str | None = None

Description of the variable; CommonMark is allowed.

examples: list[str] | None = None

Example values.

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

Specification extensions; every key must start with x-.