AsyncAPI belgesi

Consumer, kabul edilen handler planı ve effective topology’den immutable AsyncAPI 3.1.0 belgesi üretebilir. Belge servisi başarılı startup sonrasında DI container’a bağlanır. Framework otomatik HTTP route, dosya, UI veya publisher operation oluşturmaz; yayınlama biçimini uygulama seçer.

Feature ve schema tipi#

[dependencies]
lilyrs = { version = "0.1.0", features = ["consumer-asyncapi"] }
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Public config ve model tipleri lilyrs::consumer içindedir. JsonSchema için aynı modülün schemars re-export’unu kullanın; bağımsız farklı sürüm eklemeyin. Queue-only queue-asyncapi metadata desteği tek başına Consumer document service’i kurmaz. lilyrs::asyncapi adında ayrı bir facade modülü yoktur.

Tam handler ve document builder örneği#

Bu modülü ilk uygulamanın handler’ı yerine kullanın. Queue name ve routing_key değerlerini docs.api.events, exchange_name değerini docs.api yapın; bağlantı ve altı retention değerini koruyun. documented_builder(), RabbitMQ bağlantı/topology yapılandırmasını veya lily.toml dosyasını üretmez; yalnız AsyncAPI config’ini kurar. main veya managed host bu builder’ı çalıştırır.

use lilyrs::consumer::{
    AsyncApiBuildError, AsyncApiConfig, AsyncApiSecurityScheme, AsyncApiServer,
    AsyncApiServerProtocol, AsyncApiTag, Consumer, ConsumerAsyncApiService,
    ConsumerBuilder, Extensions, Injectable, ServiceTrait,
};
use lilyrs::consumer::schemars::{self, JsonSchema};
use lilyrs::queue::{Json, QueueHandlerError, asyncapi, queue, queue_service};
use serde::Deserialize;

#[derive(Deserialize, JsonSchema)]
struct ApiEvent { id: String }

#[derive(Injectable)]
#[service(lifetime = "Scoped")]
struct ApiWorker;
impl ServiceTrait for ApiWorker {}

#[queue_service]
#[asyncapi(tag = "orders", security = "consumer-auth")]
impl ApiWorker {
    #[queue("docs.api.events", version = 1, content = "json")]
    #[asyncapi(operation_id = "consumeApiEventV1", summary = "Apply one event", example = r#"{"id":"order-42"}"#)]
    async fn apply(&self, Json(event): Json<ApiEvent>) -> Result<(), QueueHandlerError> {
        if event.id.is_empty() {
            return Err(QueueHandlerError::permanent("EVENT_INVALID"));
        }
        Ok(())
    }
}

pub fn documented_builder() -> Result<ConsumerBuilder, AsyncApiBuildError> {
    let mut document = AsyncApiConfig::new("Documentation consumer", "1.0.0")?;
    document.add_tag(AsyncApiTag::new("orders")?)?;
    document.add_security_scheme(AsyncApiSecurityScheme::user_password("consumer-auth")?)?;
    document.add_server(AsyncApiServer::new(
        "public-broker", "rabbitmq.example.com:5671", AsyncApiServerProtocol::Amqps,
    )?)?;
    Ok(Consumer::builder().asyncapi(document))
}

// Call after successful managed startup through the same caller-owned container.
pub async fn document_bytes(extensions: &Extensions) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let document = extensions.get_service::<ConsumerAsyncApiService>(None).await?;
    Ok(document.canonical_json()?.to_vec())
}

Tam asyncapi.rs örneğini indirin.

Metadata contract kuralları#

Belge üretimini açtığınızda bütün aktif handler’ların documented veya explicit skip durumu tutarlı olmalıdır. Eksik metadata sessizce atlanmış endpoint gibi düşünülmez. schema ile opaque birlikte verilmez; built-in payload’ın schema otoritesi keyfi olarak değiştirilmez. Runtime ve document contract çelişkisi build hatasıdır.

Service annotation ortak tag/security bilgisi sağlar; handler kendi summary/description alanlarını belirleyebilir. Service seviyesinde skip edilmiş öğe handler tarafından yeniden documented yapılamaz. Duplicate operation ID, tanımlanmamış tag/security referansları ve builder’a ikinci .asyncapi(config) çağrısı reddedilir.

Belgeyi ne zaman okuyabilirsiniz?#

ConsumerAsyncApiService, physical queue registration ve son startup cancellation fence başarılı olduktan sonra attach edilir. Eager DI constructor’ında henüz var olmasını beklemeyin. Örnekteki document_bytes, başarılı managed startup’tan sonra aynı caller-owned container’ın Extensions handle’ıyla çağrılır.

Default owned Consumer’ın ManagedConsumer handle’ından gizli container alanı çıkaran bir public API yoktur. Belgeyi üst HTTP uygulamasından sunacaksanız shared container sahipliğini managed Consumer rehberindeki gibi kurun. Container’ı oluşturmak, Consumer’ı başlatmak ve HTTP endpoint’i bağlamak belge okuma fonksiyonundan ayrı host işleridir.

Security metadata ve gerçek authentication#

Örnekteki consumer-auth, AsyncAPI belgesinin security şemasıdır; handler’a gelen mesajı authenticate etmez. Broker credentials, TLS/mTLS ve uygulama payload doğrulaması kendi runtime mekanizmalarıdır. Belgedeki server host’una gerçek credential koymayın; örnek bu yüzden public bir placeholder kullanır.

Belge, aynı physical queue için version/content contract’larını anlatır; RabbitMQ bu bilgiye göre binary seçmez. Queue’yu paylaşan her replica, yayınlanabilecek bütün contract’ları desteklemelidir. Versioning ve rollout runtime dağıtım sınırını açıklar.