hive-c0re: annotate remaining dashboard routes with utoipa

hive-c0re/src/dashboard/extra_forges.rs

@@ -22,6 +22,7 @@ use std::path::Path;
 use axum::extract::{Form, Query};
 use axum::response::{IntoResponse, Response};
 use serde::{Deserialize, Serialize};
+use utoipa::{IntoParams, ToSchema};
 
 use super::{Ident, error_response};
 use crate::coordinator::Coordinator;
@@ -41,18 +42,18 @@ fn read_base_url(dir: &Path, label: &str) -> Option<String> {
         .map(|s| s.base_url)
 }
 
-#[derive(Serialize)]
+#[derive(Serialize, ToSchema)]
 struct ExtraForgeAccount {
     label: String,
     base_url: Option<String>,
 }
 
-#[derive(Serialize)]
+#[derive(Serialize, ToSchema)]
 struct ExtraForgesResponse {
     forges: Vec<ExtraForgeAccount>,
 }
 
-#[derive(Deserialize)]
+#[derive(Deserialize, IntoParams)]
 pub(super) struct ExtraForgesQuery {
     agent: String,
 }
@@ -62,6 +63,16 @@ pub(super) struct ExtraForgesQuery {
 /// token` file in its state dir (mirrors `matrix_accounts.rs`'s filename-scan
 /// listing). `base_url` is backfilled from the matching `forge-<label>.json`
 /// sidecar when present. Never returns a token.
+#[utoipa::path(
+    get,
+    path = "/api/extra-forges",
+    params(ExtraForgesQuery),
+    responses(
+        (status = 200, description = "provisioned extra forge accounts for the agent", body = ExtraForgesResponse),
+        (status = 500, description = "invalid agent name, or a state-dir read failed"),
+    ),
+    tag = "extra_forges"
+)]
 pub(super) async fn get_extra_forges(Query(q): Query<ExtraForgesQuery>) -> Response {
     let agent = q.agent.trim();
     let Ok(agent) = Ident::parse(agent) else {
@@ -108,7 +119,7 @@ pub(super) async fn get_extra_forges(Query(q): Query<ExtraForgesQuery>) -> Respo
 /// Form body for `POST /api/extra-forge-account` (urlencoded, the
 /// dashboard's mutation convention). `action` is `"add"` (needs `base_url` +
 /// `token`) or `"remove"`.
-#[derive(Deserialize)]
+#[derive(Deserialize, ToSchema)]
 pub(super) struct ExtraForgeAccountForm {
     agent: String,
     label: String,
@@ -117,7 +128,7 @@ pub(super) struct ExtraForgeAccountForm {
     token: Option<String>,
 }
 
-#[derive(Serialize)]
+#[derive(Serialize, ToSchema)]
 struct ExtraForgeAccountResult {
     ok: bool,
 }
@@ -127,6 +138,16 @@ struct ExtraForgeAccountResult {
 /// deletes both files. Purely local — no remote account creation or
 /// revocation, there is no admin access assumed on the external forge.
 /// Operator-authenticated (dashboard). Never echoes the token back.
+#[utoipa::path(
+    post,
+    path = "/api/extra-forge-account",
+    request_body(content = ExtraForgeAccountForm, content_type = "application/x-www-form-urlencoded"),
+    responses(
+        (status = 200, description = "provisioned or removed", body = ExtraForgeAccountResult),
+        (status = 500, description = "invalid input, or the state-dir write/delete failed"),
+    ),
+    tag = "extra_forges"
+)]
 pub(super) async fn post_extra_forge_account(Form(f): Form<ExtraForgeAccountForm>) -> Response {
     let agent = f.agent.trim();
     let label = f.label.trim();