AsyncAPI 文档

asyncapi gen 打印商店的 AsyncAPI 文档：每个主题、谁读谁写、schema、重试上限，以及应用对自己的描述。

文档由应用本身构建，所以它不可能描述代码没有使用的主题。 每个订阅是一个 receive 操作，每个回复和槽位是一个 send 操作。 载荷的 schema 来自它的 JsonSchema derive，文档注释成为描述。 max_attempts 和 dead_letter 出现在操作上，读者能看到失败的消息最终去了哪里。 AsyncAPI 讲解服务器、安全方案，以及通过 HTTP 提供文档。 文档需要 crate 的 asyncapi feature。

入口

main.rs 在内存 Broker 上构建商店。 #[ruststream::app] 给二进制程序提供命令：run 启动商店，asyncapi gen 打印文档。

宏

main.rs

/// `run` starts the shop; `asyncapi gen` prints its AsyncAPI document.
#[ruststream::app(flavor = "current_thread")]
fn app() -> impl App<State = Shop> {
    service::shop(MemoryBroker::new())
}

手写

main.rs

fn app() -> impl App<State = Shop> {
    service::shop(MemoryBroker::new())
}

/// What `#[ruststream::app]` writes: `run` starts the shop; `asyncapi gen` prints its AsyncAPI
/// document.
fn main() -> ExitCode {
    run_main_on(AppRuntime::CurrentThread, app)
}

商店对自己的描述

AppInfo 是文档的 info 块：标题、版本、描述、联系方式、许可证和标签。

宏

service.rs

/// What the AsyncAPI document says about the shop.
fn info() -> AppInfo {
    AppInfo::new("shop", "0.1.0")
        .description("Takes orders, charges them, ships them and tells the customer.")
        .contact(Contact::new().name("Shop team").email("shop@example.com"))
        .license(License::new("Apache-2.0"))
        .tag(Tag::new("orders"))
}

手写

service.rs

/// What the AsyncAPI document says about the shop.
fn info() -> AppInfo {
    AppInfo::new("shop", "0.1.0")
        .description("Takes orders, charges them, ships them and tells the customer.")
        .contact(Contact::new().name("Shop team").email("shop@example.com"))
        .license(License::new("Apache-2.0"))
        .tag(Tag::new("orders"))
}

文档

cargo run --example guide --features testing,macros,memory,json,cbor,asyncapi -- asyncapi gen --yaml

charge 的操作读取主题，在 payments.settled 上回复，并声明上限：

receive_payments_requested:
  action: receive
  channel:
    $ref: '#/channels/payments.requested'
  messages:
  - $ref: '#/channels/payments.requested/messages/PaymentRequest'
  description: Charges an order through the payment provider.
  reply:
    channel:
      $ref: '#/channels/payments.settled'
    messages:
    - $ref: '#/channels/payments.settled/messages/Paid'
  x-ruststream-retry:
    maxAttempts: 5
    deadLetter: payments.dead

商店的两种形式生成相同的文档。 两者各有一个测试，把文档与 examples/guide/asyncapi.json 比较，所以主题的改动会在评审中显现出来。