hive-c0re: annotate the 3 SSE/stream dashboard routes with utoipa

hive-c0re/src/dashboard/state_snapshot.rs

@@ -18,6 +18,7 @@ use hive_sh4re::Approval;
 use serde::{Deserialize, Serialize};
 use tokio_stream::wrappers::BroadcastStream;
 use tokio_stream::{Stream, StreamExt};
+use utoipa::IntoParams;
 
 use crate::container_view::ContainerView;
 
@@ -655,6 +656,17 @@ fn build_approval_views(approvals: Vec<Approval>) -> Vec<ApprovalView> {
     out
 }
 
+#[utoipa::path(
+    get,
+    path = "/api/dashboard/history",
+    responses(
+        (status = 200, description = "`{ seq, events }` — up to the last 200 \
+            broker messages as `DashboardEvent::Sent`/`Delivered` JSON, plus \
+            `seq`: the dashboard channel's high-water mark at fetch time \
+            (used by clients to dedupe against buffered live SSE frames)"),
+    ),
+    tag = "state_snapshot"
+)]
 pub(super) async fn dashboard_history(State(state): State<AppState>) -> Response {
     // Backfill source for the dashboard terminal. Returns up to ~200
     // historical broker messages (no other event kinds are persisted)
@@ -731,7 +743,7 @@ pub(super) async fn dashboard_history(State(state): State<AppState>) -> Response
 /// Useful for narrow pages (e.g. `flow.js` only cares about `sent`
 /// / `delivered` / `container_state_changed` / `container_removed`)
 /// that want to drop the dispatch overhead on every unrelated mutation.
-#[derive(Deserialize, Default)]
+#[derive(Deserialize, Default, IntoParams)]
 pub(super) struct DashboardStreamQuery {
     /// Comma-separated event kinds to forward. Each token is
     /// trimmed; unknown kinds are silently ignored on lookup
@@ -739,6 +751,18 @@ pub(super) struct DashboardStreamQuery {
     kinds: Option<String>,
 }
 
+#[utoipa::path(
+    get,
+    path = "/api/dashboard/stream",
+    params(DashboardStreamQuery),
+    responses(
+        (status = 200, description = "server-sent event stream; each event's \
+            `data` is a JSON-serialised `DashboardEvent` (seq-tagged; pair \
+            with `/api/dashboard/history` to backfill + dedupe on connect)",
+            body = String, content_type = "text/event-stream"),
+    ),
+    tag = "state_snapshot"
+)]
 pub(super) async fn dashboard_stream(
     State(state): State<AppState>,
     axum::extract::Query(q): axum::extract::Query<DashboardStreamQuery>,