build_spec

build_spec reads the AsyncAPI document of a service from its app value, the same value main runs.

The document follows AsyncAPI 3.1. It is read from what the app registers, so it describes the handlers the service mounts and nothing else. Each subscriber becomes a channel named after its subscription, a receive operation, and a message component for its input type. The handler's doc comment is the operation's description, and the input type's doc comment is the message's. A reply rides the receive operation, and each message an Out slot declares gets a send operation. The result is a Spec: plain data with public fields, which a test reads and a tool may complete before it is serialized. The document is built when the function is called, so it costs the running service nothing. The asyncapi feature turns it on. The example runs with cargo test --example asyncapi_generation --features macros,memory,asyncapi.

Example

Macros

examples/asyncapi_generation.rs

/// Accepts every order placed in the shop.
#[subscriber("orders")]
async fn accept(order: &Order) -> HandlerOutcome {
    tracing::info!(order.id, item = %order.item, "accepted");
    HandlerOutcome::ack()
}

fn app() -> impl App {
    RustStream::new(AppInfo::new("orders", "0.1.0")).with_broker(MemoryBroker::new(), |b| {
        b.include(accept);
    })
}

/// The document of the service, read from the same app value `main` runs.
fn document() -> Spec {
    build_spec(&app())
}

Manual

examples/manual/asyncapi_generation.rs

/// The handler `#[subscriber("orders")]` writes for the body.
struct Accept;

impl Handle<Order> for Accept {
    fn handle(
        &self,
        order: &Order,
        _outs: &(),
        _ctx: &mut Context<'_>,
    ) -> impl Future<Output = Result<(), HandlerOutcome>> {
        tracing::info!(order.id, item = %order.item, "accepted");
        ready(Ok(()))
    }
}

fn app() -> impl App {
    RustStream::new(AppInfo::new("orders", "0.1.0")).with_broker(MemoryBroker::new(), |b| {
        b.include(
            subscriber("orders", Accept)
                .describe("Accepts every order placed in the shop.")
                .build(),
        );
    })
}

/// The document of the service, read from the same app value `main` runs.
fn document() -> Spec {
    build_spec(&app())
}