docs(larql-server): Added Swagger UI for API Documentation

crates/larql-server/Cargo.toml

@@ -46,6 +46,8 @@ serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
 thiserror = { workspace = true }
 base64 = "0.22"
+utoipa = { version = "5", features = ["axum_extras", "preserve_order"] }
+utoipa-swagger-ui = { version = "9", features = ["axum"] }
 
 [features]
 default = []

crates/larql-server/src/bootstrap.rs

@@ -523,6 +523,10 @@ pub struct Cli {
     #[arg(long)]
     pub cors: bool,
 
+    /// Disable the built-in Swagger UI and /v1/openapi.json endpoint.
+    #[arg(long)]
+    pub no_docs: bool,
+
     /// API key for authentication (clients send Authorization: Bearer <key>).
     #[arg(long)]
     pub api_key: Option<String>,
@@ -869,6 +873,14 @@ pub async fn serve(cli: Cli) -> Result<(), BoxError> {
         }
     }
 
+    // OpenAPI / Swagger UI. Mounted before auth so the docs stay reachable
+    // without the API key — consistent with --cors behavior. Flip the
+    // ordering if operators want docs gated.
+    if !cli.no_docs {
+        app = app.merge(crate::openapi::swagger_router());
+        info!("OpenAPI: /swagger-ui and /v1/openapi.json enabled");
+    }
+
     // Auth middleware.
     if cli.api_key.is_some() {
         app = app.layer(middleware::from_fn_with_state(

crates/larql-server/src/error.rs

@@ -2,6 +2,15 @@
 
 use axum::http::StatusCode;
 use axum::response::{IntoResponse, Response};
+use serde::Serialize;
+use utoipa::ToSchema;
+
+/// JSON body returned for every error response.
+#[derive(Debug, Serialize, ToSchema)]
+pub struct ErrorBody {
+    /// Human-readable error message.
+    pub error: String,
+}
 
 #[derive(Debug, thiserror::Error)]
 pub enum ServerError {
@@ -30,7 +39,6 @@ impl IntoResponse for ServerError {
             ServerError::Internal(msg) => (StatusCode::INTERNAL_SERVER_ERROR, msg.clone()),
         };
 
-        let body = serde_json::json!({ "error": message });
-        (status, axum::Json(body)).into_response()
+        (status, axum::Json(ErrorBody { error: message })).into_response()
     }
 }

crates/larql-server/src/lib.rs

@@ -17,6 +17,7 @@ pub mod ffn_l2_cache;
 pub mod grpc;
 pub mod grpc_expert;
 pub mod http;
+pub mod openapi;
 pub mod ratelimit;
 pub mod routes;
 pub mod session;