Skip to content

OPENAPI.md

Latest commit

 

History

History
65 lines (50 loc) · 2.7 KB

OPENAPI.md

File metadata and controls

65 lines (50 loc) · 2.7 KB
Raw

OpenAPI (utoipa explorers)

serenade-openapi is the framework crate for OpenAPI document helpers and optional explorer UIs. Applications still declare their own #[derive(OpenApi)] paths and schemas; Serenade owns path conventions and UI mounting.

Piece Role
OpenApiUiPaths Default /swagger-ui/, /redoc, /rapidoc, /scalar, /openapi.json
finalize_openapi / apply_info / apply_server Title, version, servers
Feature actix configure_actix_ui mounts all four explorers on Actix

App vs framework

Owner Responsibility
Application #[derive(OpenApi)] path list, ToSchema DTOs, serving /openapi.json, dump/CI
Framework Explorer mounts, default paths, Info/servers helpers, this document

OpenAPI is opt-in: depend on serenade-openapi and enable feature actix when you want Swagger UI, Redoc, RapiDoc, and Scalar. Binaries that only need the JSON contract do not require the UI feature.

Actix beside HttpKernel listen

Mount explorers before the Serenade kernel catch-all:

use actix_web::{App, web};
use serenade_openapi::{OpenApiUiPaths, configure_actix_ui, finalize_openapi};
use utoipa::OpenApi;

#[derive(OpenApi)]
#[openapi(paths(/* app handlers */))]
struct ApiDoc;

fn app() -> App {
    let mut openapi = ApiDoc::openapi();
    finalize_openapi(
        &mut openapi,
        "my-service",
        env!("CARGO_PKG_VERSION"),
        Some("http://127.0.0.1:8080"),
    );
    let paths = OpenApiUiPaths::new();
    App::new()
        .configure(|cfg| configure_actix_ui(cfg, openapi, &paths))
        // app: GET /openapi.json from ApiDoc::openapi()
        // then: WebSocket routes, Serenade default_service / listen dispatch
}

Explorers load the JSON at OpenApiUiPaths::openapi_json (default /openapi.json). Keep that route on the app so OpenAPI dump binaries stay independent of UI crates.

Axum

No Axum mount helper in this crate. Axum apps use finalize_openapi and mount utoipa UI crates themselves.

Non-goals

  • Generating commerce/domain schemas inside Serenade
  • Replacing app utoipa::path annotations
  • Mandating explorers in every Serenade binary