add utopia for swaggerui in http-api

Author: Symbiont OSS Sync

Cargo.lock

@@ -78,6 +78,8 @@ tower = { version = "0.4", optional = true }
 tower-http = { version = "0.5", features = ["cors", "trace"], optional = true }
 tokio-tungstenite = { version = "0.21", optional = true }
 governor = { version = "0.10", optional = true }
+utoipa = { version = "4.2", features = ["axum_extras", "chrono"], optional = true }
+utoipa-swagger-ui = { version = "6.0", features = ["axum"], optional = true }
 
 # Enterprise features removed for OSS build
 
@@ -90,7 +92,7 @@ criterion = "0.5"
 default = ["vector-db", "keychain"]
 vector-db = []
 embedding-models = ["candle-core", "candle-nn", "candle-transformers", "tokenizers", "hf-hub"]
-http-api = ["axum", "tower", "tower-http", "tokio-tungstenite", "governor"]
+http-api = ["axum", "tower", "tower-http", "tokio-tungstenite", "governor", "utoipa", "utoipa-swagger-ui"]
 http-input = ["axum", "tower", "tower-http"]
 keychain = ["keyring", "security-framework", "secret-service", "winapi"]
 enterprise = []  # Enterprise feature for conditional compilation

crates/runtime/Cargo.toml

@@ -55,7 +55,8 @@ pub async fn auth_middleware(request: Request, next: Next) -> Result<Response, S
 
 /// Global rate limiter store for per-IP rate limiting
 #[cfg(feature = "http-api")]
-static RATE_LIMITERS: OnceLock<DashMap<IpAddr, Arc<RateLimiter<NotKeyed, InMemoryState, DefaultClock>>>> = OnceLock::new();
+type IpRateLimiter = Arc<RateLimiter<NotKeyed, InMemoryState, DefaultClock>>;
+static RATE_LIMITERS: OnceLock<DashMap<IpAddr, IpRateLimiter>> = OnceLock::new();
 
 /// Get or create a rate limiter for a specific IP address
 #[cfg(feature = "http-api")]

crates/runtime/src/api/middleware.rs

@@ -12,6 +12,9 @@ use axum::{
 #[cfg(feature = "http-api")]
 use std::sync::Arc;
 
+#[cfg(feature = "http-api")]
+use utoipa;
+
 #[cfg(feature = "http-api")]
 use super::traits::RuntimeApiProvider;
 
@@ -23,6 +26,16 @@ use crate::types::AgentId;
 
 /// Workflow execution endpoint handler
 #[cfg(feature = "http-api")]
+#[utoipa::path(
+    post,
+    path = "/api/v1/workflows/execute",
+    request_body = WorkflowExecutionRequest,
+    responses(
+        (status = 200, description = "Workflow executed successfully", body = serde_json::Value),
+        (status = 500, description = "Internal server error", body = ErrorResponse)
+    ),
+    tag = "workflows"
+)]
 pub async fn execute_workflow(
     State(provider): State<Arc<dyn RuntimeApiProvider>>,
     Json(request): Json<WorkflowExecutionRequest>,
@@ -42,6 +55,18 @@ pub async fn execute_workflow(
 
 /// Agent status endpoint handler
 #[cfg(feature = "http-api")]
+#[utoipa::path(
+    get,
+    path = "/api/v1/agents/{id}/status",
+    params(
+        ("id" = AgentId, Path, description = "Agent identifier")
+    ),
+    responses(
+        (status = 200, description = "Agent status retrieved successfully", body = AgentStatusResponse),
+        (status = 404, description = "Agent not found", body = ErrorResponse)
+    ),
+    tag = "agents"
+)]
 pub async fn get_agent_status(
     State(provider): State<Arc<dyn RuntimeApiProvider>>,
     Path(agent_id): Path<AgentId>,
@@ -61,6 +86,15 @@ pub async fn get_agent_status(
 
 /// List agents endpoint handler
 #[cfg(feature = "http-api")]
+#[utoipa::path(
+    get,
+    path = "/api/v1/agents",
+    responses(
+        (status = 200, description = "Agents listed successfully", body = Vec<String>),
+        (status = 500, description = "Internal server error", body = ErrorResponse)
+    ),
+    tag = "agents"
+)]
 pub async fn list_agents(
     State(provider): State<Arc<dyn RuntimeApiProvider>>,
 ) -> Result<Json<Vec<String>>, (StatusCode, Json<ErrorResponse>)> {
@@ -82,6 +116,15 @@ pub async fn list_agents(
 
 /// System metrics endpoint handler
 #[cfg(feature = "http-api")]
+#[utoipa::path(
+    get,
+    path = "/api/v1/metrics",
+    responses(
+        (status = 200, description = "Metrics retrieved successfully", body = serde_json::Value),
+        (status = 500, description = "Internal server error", body = ErrorResponse)
+    ),
+    tag = "system"
+)]
 pub async fn get_metrics(
     State(provider): State<Arc<dyn RuntimeApiProvider>>,
 ) -> Result<Json<serde_json::Value>, (StatusCode, Json<ErrorResponse>)> {
@@ -100,6 +143,16 @@ pub async fn get_metrics(
 
 /// Create agent endpoint handler
 #[cfg(feature = "http-api")]
+#[utoipa::path(
+    post,
+    path = "/api/v1/agents",
+    request_body = CreateAgentRequest,
+    responses(
+        (status = 200, description = "Agent created successfully", body = CreateAgentResponse),
+        (status = 500, description = "Internal server error", body = ErrorResponse)
+    ),
+    tag = "agents"
+)]
 pub async fn create_agent(
     State(provider): State<Arc<dyn RuntimeApiProvider>>,
     Json(request): Json<CreateAgentRequest>,
@@ -119,6 +172,19 @@ pub async fn create_agent(
 
 /// Update agent endpoint handler
 #[cfg(feature = "http-api")]
+#[utoipa::path(
+    put,
+    path = "/api/v1/agents/{id}",
+    params(
+        ("id" = AgentId, Path, description = "Agent identifier")
+    ),
+    request_body = UpdateAgentRequest,
+    responses(
+        (status = 200, description = "Agent updated successfully", body = UpdateAgentResponse),
+        (status = 500, description = "Internal server error", body = ErrorResponse)
+    ),
+    tag = "agents"
+)]
 pub async fn update_agent(
     State(provider): State<Arc<dyn RuntimeApiProvider>>,
     Path(agent_id): Path<AgentId>,
@@ -139,6 +205,18 @@ pub async fn update_agent(
 
 /// Delete agent endpoint handler
 #[cfg(feature = "http-api")]
+#[utoipa::path(
+    delete,
+    path = "/api/v1/agents/{id}",
+    params(
+        ("id" = AgentId, Path, description = "Agent identifier")
+    ),
+    responses(
+        (status = 200, description = "Agent deleted successfully", body = DeleteAgentResponse),
+        (status = 500, description = "Internal server error", body = ErrorResponse)
+    ),
+    tag = "agents"
+)]
 pub async fn delete_agent(
     State(provider): State<Arc<dyn RuntimeApiProvider>>,
     Path(agent_id): Path<AgentId>,
@@ -158,6 +236,19 @@ pub async fn delete_agent(
 
 /// Execute agent endpoint handler
 #[cfg(feature = "http-api")]
+#[utoipa::path(
+    post,
+    path = "/api/v1/agents/{id}/execute",
+    params(
+        ("id" = AgentId, Path, description = "Agent identifier")
+    ),
+    request_body = ExecuteAgentRequest,
+    responses(
+        (status = 200, description = "Agent executed successfully", body = ExecuteAgentResponse),
+        (status = 500, description = "Internal server error", body = ErrorResponse)
+    ),
+    tag = "agents"
+)]
 pub async fn execute_agent(
     State(provider): State<Arc<dyn RuntimeApiProvider>>,
     Path(agent_id): Path<AgentId>,
@@ -178,6 +269,18 @@ pub async fn execute_agent(
 
 /// Get agent execution history endpoint handler
 #[cfg(feature = "http-api")]
+#[utoipa::path(
+    get,
+    path = "/api/v1/agents/{id}/history",
+    params(
+        ("id" = AgentId, Path, description = "Agent identifier")
+    ),
+    responses(
+        (status = 200, description = "Agent history retrieved successfully", body = GetAgentHistoryResponse),
+        (status = 500, description = "Internal server error", body = ErrorResponse)
+    ),
+    tag = "agents"
+)]
 pub async fn get_agent_history(
     State(provider): State<Arc<dyn RuntimeApiProvider>>,
     Path(agent_id): Path<AgentId>,