asyncapi_rust/
lib.rs

1//! # asyncapi-rust
2//!
3//! Generate [AsyncAPI 3.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0)
4//! specifications from Rust code using procedural macros.
5//!
6//! Similar to how [`utoipa`](https://crates.io/crates/utoipa) generates OpenAPI specs for REST APIs,
7//! `asyncapi-rust` generates AsyncAPI specs for WebSocket and other async protocols.
8//!
9//! ## Quick Start
10//!
11//! Add to your `Cargo.toml`:
12//! ```toml
13//! [dependencies]
14//! asyncapi-rust = "0.1"
15//! serde = { version = "1.0", features = ["derive"] }
16//! schemars = { version = "0.8", features = ["derive"] }
17//! ```
18//!
19//! Define your WebSocket messages:
20//!
21//! ```rust,ignore
22//! use asyncapi_rust::{AsyncApi, ToAsyncApiMessage, schemars::JsonSchema};
23//! use serde::{Deserialize, Serialize};
24//!
25//! /// WebSocket messages for a chat application
26//! #[derive(Serialize, Deserialize, JsonSchema, ToAsyncApiMessage)]
27//! #[serde(tag = "type")]
28//! pub enum ChatMessage {
29//!     /// User joins a chat room
30//!     #[serde(rename = "user.join")]
31//!     #[asyncapi(summary = "User joins", description = "Sent when a user enters a room")]
32//!     UserJoin { username: String, room: String },
33//!
34//!     /// Send a chat message
35//!     #[serde(rename = "chat.message")]
36//!     #[asyncapi(summary = "Chat message", description = "Broadcast to all users in a room")]
37//!     Chat { username: String, room: String, text: String },
38//! }
39//!
40//! /// Complete API specification
41//! #[derive(AsyncApi)]
42//! #[asyncapi(title = "Chat API", version = "1.0.0")]
43//! #[asyncapi_server(name = "production", host = "api.example.com", protocol = "wss")]
44//! #[asyncapi_channel(name = "chat", address = "/ws/chat")]
45//! #[asyncapi_operation(name = "sendMessage", action = "send", channel = "chat")]
46//! #[asyncapi_operation(name = "receiveMessage", action = "receive", channel = "chat")]
47//! struct ChatApi;
48//!
49//! fn main() {
50//!     // Generate complete specification
51//!     let spec = ChatApi::asyncapi_spec();
52//!
53//!     // Generate message schemas
54//!     let messages = ChatMessage::asyncapi_messages();
55//!
56//!     // Serialize to JSON
57//!     println!("{}", serde_json::to_string_pretty(&spec).unwrap());
58//! }
59//! ```
60//!
61//! ## Core Concepts
62//!
63//! ### Message Types with `#[derive(ToAsyncApiMessage)]`
64//!
65//! Generate message metadata and JSON schemas from your Rust types:
66//!
67//! - Uses [`serde`](https://serde.rs) for JSON serialization
68//! - Uses [`schemars`](https://docs.rs/schemars) for JSON Schema generation
69//! - Respects `#[serde(...)]` attributes (`rename`, `tag`, etc.)
70//! - Supports `#[asyncapi(...)]` helper attributes for documentation
71//!
72//! ### Complete Specs with `#[derive(AsyncApi)]`
73//!
74//! Generate complete AsyncAPI specifications declaratively:
75//!
76//! - `#[asyncapi(...)]` - Basic info (title, version, description)
77//! - `#[asyncapi_server(...)]` - Server definitions
78//! - `#[asyncapi_channel(...)]` - Channel definitions
79//! - `#[asyncapi_operation(...)]` - Operation definitions
80//!
81//! ## Framework Integration
82//!
83//! Works with any WebSocket framework:
84//!
85//! - **actix-web + actix-ws** - See `examples/actix_websocket.rs`
86//! - **axum** - See `examples/axum_websocket.rs`
87//! - **tungstenite** - See `examples/framework_integration_guide.rs`
88//!
89//! The same message types are used in both runtime handlers and documentation.
90//!
91//! ## Features
92//!
93//! - **Code-first**: Generate specs from Rust types, not YAML
94//! - **Compile-time**: Zero runtime cost, all generation at build time
95//! - **Type-safe**: Compile errors if documentation drifts from code
96//! - **Framework agnostic**: Works with actix-ws, axum, or any serde-compatible types
97//! - **Binary protocols**: Support for mixed text/binary WebSocket messages
98//!
99//! ## Examples
100//!
101//! See the `examples/` directory for complete working examples:
102//!
103//! - `simple.rs` - Basic message types with schema generation
104//! - `chat_api.rs` - Complete AsyncAPI 3.0 specification
105//! - `asyncapi_derive.rs` - Using `#[derive(AsyncApi)]`
106//! - `generate_spec_file.rs` - Generating specification files
107//! - `full_asyncapi_derive.rs` - Complete spec with servers, channels, operations
108//! - `actix_websocket.rs` - Real-world actix-web integration
109//! - `axum_websocket.rs` - Real-world axum integration
110//! - `framework_integration_guide.rs` - Comprehensive framework guide
111//!
112//! Run any example:
113//! ```bash
114//! cargo run --example actix_websocket
115//! ```
116//!
117//! ## Generating Documentation Files
118//!
119//! Create a binary to generate AsyncAPI spec files:
120//!
121//! ```rust,ignore
122//! // bin/generate-asyncapi.rs
123//! use my_project::MyApi;
124//!
125//! fn main() {
126//!     let spec = MyApi::asyncapi_spec();
127//!     let json = serde_json::to_string_pretty(&spec).unwrap();
128//!     std::fs::write("docs/asyncapi.json", json).unwrap();
129//! }
130//! ```
131//!
132//! Then run: `cargo run --bin generate-asyncapi`
133//!
134//! ## Further Reading
135//!
136//! - [AsyncAPI Specification](https://www.asyncapi.com/docs/reference/specification/v3.0.0)
137//! - [GitHub Repository](https://github.com/mlilback/asyncapi-rust)
138//! - [Examples Directory](https://github.com/mlilback/asyncapi-rust/tree/main/asyncapi-rust/examples)
139
140#![deny(missing_docs)]
141#![warn(clippy::all)]
142
143// Re-export proc macros from asyncapi-rust-codegen
144pub use asyncapi_rust_codegen::{AsyncApi, ToAsyncApiMessage};
145
146// Re-export models
147pub use asyncapi_rust_models::*;
148
149// Re-export commonly used types
150pub use schemars;
151pub use serde::{Deserialize, Serialize};
152pub use serde_json;
153
154#[cfg(test)]
155mod tests {
156    #[test]
157    fn test_basic_import() {
158        // Verify exports are accessible
159        // Actual functionality tests will be in integration tests
160    }
161}
asyncapi_rust/lib.rs

asyncapi_rust/
lib.rs
