OpenAPI · Lily

Route metadata’sından OpenAPI 3.1 belgesi üretin ve açıkça tanımladığınız endpoint’te yayımlayın.

OpenAPI üç adımdan oluşur: controller/action metadata’sı, builder config’i ve belgeyi döndüren endpoint. JSON veya Swagger UI route’u otomatik eklenmez.

Metadata ve JSON endpoint’i#

Bu örnek ayrı küçük bir uygulama modülüdür. İlk uygulamanın HTTP ve Serde bağımlılıklarını kullanır:

use std::sync::Arc;
use lilyrs::http_api::{
    controller, AppBuilder, Controller, ControllerInitError, ControllerTrait,
    Extensions, HttpApiError, OpenApiConfig, OpenApiJson, OpenApiService, Service,
};
use lilyrs::http_api::utoipa::{self, ToSchema};
use serde::Serialize;

#[derive(Serialize, ToSchema)]
struct Status { ready: bool }

#[derive(Controller)]
#[base_path("/contract")]
#[openapi(tag = "Contract")]
struct ContractController;

#[lilyrs::http_api::async_trait::async_trait]
impl ControllerTrait for ContractController {
    async fn new(_: Arc<Extensions>) -> Result<Self, ControllerInitError> { Ok(Self) }
}

#[controller]
impl ContractController {
    #[get("/status")]
    #[openapi(operation_id = "contract.status", summary = "Örnek yanıt")]
    async fn status(&self) -> Result<Status, HttpApiError> { Ok(Status { ready: true }) }

    #[get("/openapi.json")]
    #[openapi(skip)]
    async fn document(&self, Service(openapi): Service<OpenApiService>)
        -> Result<OpenApiJson, HttpApiError>
    {
        Ok(openapi.json()?)
    }
}

async fn run() -> Result<(), Box<dyn std::error::Error>> {
    let config = OpenApiConfig::new("Örnek API", "1.0.0")?;
    AppBuilder::new("127.0.0.1:8080").tls_disabled()
        .openapi(config).build().await?.start().await?;
    Ok(())
}

Örnekteki run() async fonksiyonunu ilk uygulamanın runtime girişinden çalıştırın. GET /contract/openapi.json belgeyi, GET /contract/status örnek yanıtı verir. Status action’ındaki ready: true yalnız DTO örneğidir; gerçek readiness için HttpHealthService kullanın.

Schema import’u#

use lilyrs::http_api::utoipa::{self, ToSchema} içindeki self önemlidir. Upstream derive’ın ürettiği utoipa yolu bu import ile çözülür.

Bütün route’ları kapsama#

OpenAPI etkinleştirildiğinde aynı binary’deki diğer controller’lar da metadata veya #[openapi(skip)] taşımalıdır. Belge endpoint’i örnekte kendi dokümanından çıkarılmıştır.

OpenApiService constructor’da çözülebilir; ancak json veya snapshot o sırada okunmaz. Belge bütün route’lar hazırlandıktan sonra bağlanır. Action’da veya build sonrası okuyun.

Belge erişimi ve UI#

JSON endpoint’inin auth politikasını uygulamanız seçer. Swagger UI isterseniz UI dosyalarını ayrıca barındırıp bu endpoint’e bağlayın. OpenAPI security metadata’sı çalışan bir guard yerine geçmez; ayrıntılar şema ve security sayfasındadır.