hive-c0re: annotate remaining dashboard routes with utoipa

hive-c0re/src/dashboard/build_logs.rs

@@ -17,10 +17,12 @@ use axum::{
 use serde::{Deserialize, Serialize};
 use tokio_stream::Stream;
 use tokio_stream::wrappers::ReceiverStream;
+use utoipa::IntoParams;
 
 use super::{AppState, Ident, error_response};
+use crate::build_logs::{BuildLogFull, BuildLogHeader};
 
-#[derive(Deserialize)]
+#[derive(Deserialize, IntoParams)]
 pub(super) struct BuildLogsAllQuery {
     /// Max rows to return. Capped at 100. Default 30.
     #[serde(default)]
@@ -29,6 +31,16 @@ pub(super) struct BuildLogsAllQuery {
 
 /// `GET /api/build-logs?limit=N` — most-recent build log headers across
 /// all agents, newest first. Same JSON shape as the per-agent endpoint.
+#[utoipa::path(
+    get,
+    path = "/api/build-logs",
+    params(BuildLogsAllQuery),
+    responses(
+        (status = 200, description = "recent build log headers, newest first", body = Vec<BuildLogHeader>),
+        (status = 500, description = "sqlite read failed"),
+    ),
+    tag = "build_logs"
+)]
 pub(super) async fn get_build_logs_all(
     State(state): State<AppState>,
     axum::extract::Query(q): axum::extract::Query<BuildLogsAllQuery>,
@@ -40,7 +52,7 @@ pub(super) async fn get_build_logs_all(
     }
 }
 
-#[derive(Deserialize)]
+#[derive(Deserialize, IntoParams)]
 pub(super) struct BuildLogsQuery {
     /// Maximum number of rows to return. Capped server-side at 50
     /// (see `build_logs::list_recent_for_agent`). Default 10.
@@ -53,6 +65,20 @@ pub(super) struct BuildLogsQuery {
 /// `Vec<BuildLogHeader>` (JSON). Limit defaults to 10, server-side
 /// cap at 50. Backs the per-agent log chip in the agent card and
 /// the side-panel header list.
+#[utoipa::path(
+    get,
+    path = "/api/build-logs/{agent}",
+    params(
+        ("agent" = String, Path, description = "agent name"),
+        BuildLogsQuery,
+    ),
+    responses(
+        (status = 200, description = "recent build log headers for the agent, newest first", body = Vec<BuildLogHeader>),
+        (status = 400, description = "bad agent name"),
+        (status = 500, description = "sqlite read failed"),
+    ),
+    tag = "build_logs"
+)]
 pub(super) async fn get_build_logs_agent(
     State(state): State<AppState>,
     AxumPath(name): AxumPath<String>,
@@ -79,6 +105,17 @@ pub(super) async fn get_build_logs_agent(
 /// stderr concatenated) by id. Returns `BuildLogFull` (JSON), or
 /// HTTP 404 when the id doesn't exist (vacuum-reaped, or the
 /// operator passed a stale id from a refresh race).
+#[utoipa::path(
+    get,
+    path = "/api/build-logs/id/{id}",
+    params(("id" = i64, Path, description = "build log row id")),
+    responses(
+        (status = 200, description = "full build log row", body = BuildLogFull),
+        (status = 404, description = "no such build log row"),
+        (status = 500, description = "sqlite read failed"),
+    ),
+    tag = "build_logs"
+)]
 pub(super) async fn get_build_log_full(
     State(state): State<AppState>,
     AxumPath(id): AxumPath<i64>,
@@ -96,6 +133,17 @@ pub(super) async fn get_build_log_full(
 /// node has no linked log (the client gates the request on `NodeView.has_log`,
 /// but a vacuum race can still 404). This is the on-demand log fetch the
 /// raw-graph dashboard uses instead of an inline `build_log_id` on the wire.
+#[utoipa::path(
+    get,
+    path = "/api/build-log/{node_id}",
+    params(("node_id" = u64, Path, description = "job-queue node id")),
+    responses(
+        (status = 200, description = "full build log row for the node's linked log", body = BuildLogFull),
+        (status = 404, description = "node has no linked build log, or the log row is gone"),
+        (status = 500, description = "sqlite read failed"),
+    ),
+    tag = "build_logs"
+)]
 pub(super) async fn get_build_log_for_node(
     State(state): State<AppState>,
     AxumPath(node_id): AxumPath<u64>,
@@ -112,6 +160,17 @@ pub(super) async fn get_build_log_for_node(
 
 /// `GET /api/build-log/{node_id}/raw` — the node's build log as `text/plain`
 /// for download (delegates to `get_build_log_raw` after resolving the node id).
+#[utoipa::path(
+    get,
+    path = "/api/build-log/{node_id}/raw",
+    params(("node_id" = u64, Path, description = "job-queue node id")),
+    responses(
+        (status = 200, description = "build log text for download", body = String, content_type = "text/plain"),
+        (status = 404, description = "node has no linked build log, or the log row is gone"),
+        (status = 500, description = "sqlite read failed"),
+    ),
+    tag = "build_logs"
+)]
 pub(super) async fn get_build_log_raw_for_node(
     State(state): State<AppState>,
     AxumPath(node_id): AxumPath<u64>,
@@ -239,6 +298,17 @@ pub(super) async fn get_build_log_stream(
 /// separator (same layout the JS side-panel renders). The
 /// `Content-Disposition` header triggers a browser download with a
 /// descriptive filename so the operator can save and share the log.
+#[utoipa::path(
+    get,
+    path = "/api/build-logs/id/{id}/raw",
+    params(("id" = i64, Path, description = "build log row id")),
+    responses(
+        (status = 200, description = "build log text for download", body = String, content_type = "text/plain"),
+        (status = 404, description = "no such build log row"),
+        (status = 500, description = "sqlite read failed"),
+    ),
+    tag = "build_logs"
+)]
 pub(super) async fn get_build_log_raw(
     State(state): State<AppState>,
     AxumPath(id): AxumPath<i64>,