AsyncAPI 3.0 specification generation for Rust WebSockets and async protocols

Generate AsyncAPI documentation directly from your Rust code using procedural macros. Similar to how utoipa generates OpenAPI specs for REST APIs, asyncapi-rust generates AsyncAPI specs for WebSocket and other async protocols.

• Features
• Migrating from 0.4.x
• Migrating from 0.3.x
• Migrating from 0.2.x
• Quick Start
  • Message Integration
  • Server Variables and Channel Parameters
  • Message Naming and Disambiguation
• Examples
• Motivation
• Comparison: Manual vs Generated
• Supported Frameworks
• Binary Protocol Support
• DateTime Support (Chrono)
• Generating Specification Files
• Documentation
• Roadmap
• Contributing
• License
• Statement on AI/LLM Usage
• Acknowledgments

• 🦀 Code-first: Generate specs from Rust types, not YAML
• ⚡ Compile-time: Zero runtime cost, all generation at build time
• 🔒 Type-safe: Compile errors if documentation drifts from code
• 🎯 Familiar: Follows patterns from utoipa, serde, and clap
• 🌐 Framework agnostic: Works with actix-ws, axum, or any serde-compatible types
• 📦 Binary protocols: Support for mixed text/binary WebSocket messages (Arrow IPC, Protobuf, etc.)
• 🔌 Protocol bindings: MQTT server, operation, and message bindings (more protocols planned)

New in 0.5.0: protocol bindings. Server, Operation, and Message each gained a bindings field, and MQTT server/operation/message bindings can now be declared with mqtt(...) inside the #[asyncapi_server(...)], #[asyncapi_operation(...)], and #[asyncapi(...)] attributes. See examples/mqtt_bindings.rs.

The bindings field is Option<_> with #[serde(default)] and Default, so deserialization, ..Default::default(), and read-only access compile unchanged. If you construct Server, Operation, or Message with an explicit struct literal (e.g. in tests or a custom spec builder), add the new field:

let server = asyncapi_rust::Server {
    // ...existing fields...
    bindings: None,
};

Breaking change in 0.4.0: all map-typed fields on model structs (servers, channels, operations, components.messages, components.schemas, properties, etc.) changed from std::collections::HashMap to indexmap::IndexMap. This makes generated spec output byte-stable across builds — previously HashMap's random iteration order caused churn in downstream TypeScript codegen and other consumers even when the API hadn't changed.

If you construct model structs directly (e.g. in tests or a custom spec builder), replace HashMap::new() with IndexMap::new(). indexmap is re-exported from asyncapi_rust so you don't need to add it to your own Cargo.toml:

use asyncapi_rust::indexmap::IndexMap;

let mut servers = IndexMap::new();
servers.insert("production".to_string(), my_server);

Code that only reads from these fields (iterating, .get(), .contains_key()) compiles unchanged — IndexMap has the same API as HashMap for read operations.

Breaking change in 0.3.0: message names in components.messages and asyncapi_message_names() now derive from the Rust variant identifier, not the serde rename string.

The serde rename string remains the wire discriminant inside the payload schema — wire format is unchanged.

Other 0.3.0 additions:

• #[asyncapi(message_name = "CustomName")] per-variant override for disambiguation
• Runtime collision detection: two enums sharing a variant identifier in the same document panic with a clear error instead of silently overwriting
• Schema::Any handles serde_json::Value fields without panicking
• AsyncAPI 3.0–compliant Parameter object (removed schema, added default, enum_values, examples, location)
• Shared $defs are hoisted to components.schemas; message payloads reference them via $ref: "#/components/schemas/X"

Add to your Cargo.toml:

[dependencies]
asyncapi-rust = "0.4"
serde = { version = "1.0", features = ["derive"] }
schemars = { version = "1.1", features = ["derive"] }

# Optional: for chrono datetime support in schemas
chrono = { version = "0.4", features = ["serde"] }
schemars = { version = "1.1", features = ["derive", "chrono04"] }

Define your WebSocket messages:

use asyncapi_rust::{schemars::JsonSchema, ToAsyncApiMessage};
use serde::{Deserialize, Serialize};

/// WebSocket messages for a chat application
#[derive(Serialize, Deserialize, JsonSchema, ToAsyncApiMessage)]
#[serde(tag = "type")]
pub enum ChatMessage {
    /// User joins a chat room
    #[serde(rename = "user.join")]
    UserJoin { username: String, room: String },

    /// Send a chat message
    #[serde(rename = "chat.message")]
    Chat { username: String, room: String, text: String },
}

fn main() {
    // Get message names — returns Rust variant identifiers, not serde rename strings
    let names = ChatMessage::asyncapi_message_names();
    println!("Messages: {:?}", names); // ["UserJoin", "Chat"]

    // Generate messages with JSON schemas
    let messages = ChatMessage::asyncapi_messages();

    // Each message includes:
    // - name and title
    // - contentType: "application/json"
    // - payload: Full JSON Schema from schemars

    let json = serde_json::to_string_pretty(&messages).unwrap();
    println!("{}", json);
}

Combine message types into complete specifications using #[asyncapi_messages(...)]:

use asyncapi_rust::{AsyncApi, ToAsyncApiMessage, schemars::JsonSchema};
use serde::{Deserialize, Serialize};

// Define your message types
#[derive(Serialize, Deserialize, JsonSchema, ToAsyncApiMessage)]
#[serde(tag = "type")]
pub enum ChatMessage {
    #[serde(rename = "user.join")]
    UserJoin { username: String, room: String },

    #[serde(rename = "chat.message")]
    Chat { username: String, text: String },
}

// Reference message types in your API spec
#[derive(AsyncApi)]
#[asyncapi(title = "Chat API", version = "1.0.0")]
#[asyncapi_messages(ChatMessage)]  // Automatically includes all messages
struct ChatApi;

fn main() {
    let spec = ChatApi::asyncapi_spec();
    // spec.components.messages now contains all ChatMessage variants
    // with full JSON schemas
}

The #[asyncapi_messages(...)] attribute automatically populates the components/messages section with:

• All message definitions from referenced types
• Complete JSON schemas generated from Rust types
• Message metadata (name, summary, description, content-type)

Define dynamic server paths and channel parameters for WebSocket connections:

use asyncapi_rust::AsyncApi;

#[derive(AsyncApi)]
#[asyncapi(title = "User WebSocket API", version = "1.0.0")]
#[asyncapi_server(
    name = "production",
    host = "api.enlightenhq.com",
    protocol = "wss",
    pathname = "/api/ws/{userId}",
    variable(
        name = "userId",
        description = "Authenticated user ID",
        examples = ["12", "13"]
    )
)]
#[asyncapi_channel(
    name = "rtMessaging",
    address = "/api/ws/{userId}",
    parameter(
        name = "userId",
        description = "User ID for this WebSocket connection",
        examples = ["42", "100"]
    )
)]
struct UserApi;

Server variables define placeholders in server URLs with:

• name: Variable name (required)
• description: Human-readable description
• examples: Example values for documentation
• default: Default value if not provided
• enum_values: Restricted set of allowed values

Channel parameters define path parameters with:

• name: Parameter name (required)
• description: Human-readable description
• default: Default value if not provided
• enum_values: Restricted set of allowed values (e.g., ["v1", "v2"])
• examples: Example values for documentation (e.g., ["42", "100"])
• location: Runtime expression for the parameter's location

By default, message names in components.messages and asyncapi_message_names() are the Rust variant identifiers (UserJoin, Chat), not the serde rename strings ("user.join", "chat.message"). The serde rename is preserved as the wire discriminant inside the payload schema.

If two ToAsyncApiMessage enums in the same AsyncAPI document share a variant identifier, the runtime detects the collision and panics with a clear message. Use #[asyncapi(message_name = "…")] to disambiguate:

#[derive(Serialize, Deserialize, JsonSchema, ToAsyncApiMessage)]
#[serde(tag = "message")]
pub enum Operation {
    #[serde(rename = "get-info")]
    GetInfo { project_id: i64 },
}

#[derive(Serialize, Deserialize, JsonSchema, ToAsyncApiMessage)]
#[serde(tag = "message")]
pub enum OperationResponse {
    // Same wire discriminant as Operation::GetInfo, but a distinct message name
    #[serde(rename = "get-info")]
    #[asyncapi(message_name = "GetInfoResponse")]
    GetInfo { id: i64, label: String },
}

Both messages appear in components.messages under distinct keys (GetInfo and GetInfoResponse), with "get-info" as the wire value in both payload schemas.

#[asyncapi(message_name = "…")] attributes:

• message_name = "CustomName": Override the default (variant ident) for a single variant
• An empty serde rename (#[serde(rename = "")]) automatically falls back to the variant identifier — no override needed

See working examples in the examples/ directory:

• simple.rs - Basic message types with schema generation
• chat_api.rs - Complete AsyncAPI 3.0 specification with server, channels, and operations
• message_integration.rs - Automatic message integration with #[asyncapi_messages(...)]
• server_variables.rs - Server variables and channel parameters for dynamic paths
• mqtt_bindings.rs - MQTT server, operation, and message protocol bindings
• asyncapi_derive.rs - Using #[derive(AsyncApi)] for specs
• full_asyncapi_derive.rs - Complete spec with servers, channels, operations
• generate_spec_file.rs - Generating specification files
• actix_websocket.rs - Real-world actix-web + actix-ws integration
• axum_websocket.rs - Real-world axum WebSocket integration
• framework_integration_guide.rs - Comprehensive framework integration guide

Run any example:

cargo run --example simple
cargo run --example message_integration
cargo run --example server_variables
cargo run --example mqtt_bindings

Manually maintaining AsyncAPI specifications is error-prone and time-consuming:

• ❌ Type changes in Rust require manual YAML updates
• ❌ No compile-time validation of documentation accuracy
• ❌ Easy for docs to drift from implementation
• ❌ Repetitive work defining the same types twice

asyncapi-rust solves this by generating AsyncAPI specs directly from your Rust types, providing a single source of truth with compile-time guarantees.

Before (Manual YAML):

# asyncapi.yaml - must keep in sync manually!
components:
  messages:
    SendMessage:
      payload:
        type: object
        properties:
          type: { type: string, const: SendMessage }
          room: { type: string }
          text: { type: string }

After (Generated from Rust):

/// Send a chat message
#[derive(Serialize, Deserialize, ToAsyncApiMessage)]
#[serde(tag = "type", rename = "SendMessage")]
pub struct SendMessage {
    pub room: String,
    pub text: String,
}
// AsyncAPI YAML generated automatically at compile time!

• ✅ actix-ws - Full integration with actix-web WebSocket handlers
• ✅ axum - Integration with axum WebSocket routes
• 🔄 Framework-agnostic - Works with any serde-compatible message types