vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

hive-c0re: split OpenAPI summary/description, move param docs to params

Browse source 
utoipa splits a handler's doc comment on the first blank `///` line:
everything before it becomes the OpenAPI `summary` (shown in Swagger
UI's collapsed endpoint-list row), everything after becomes the
`description` (only shown once that row is expanded). With no blank
line, the whole doc comment becomes the summary and the description is
empty — which is what every handler in hive-c0re/src/dashboard/ was
doing, so the all-endpoints list showed full multi-sentence prose next
to every route instead of a short one-liner.

For every `#[utoipa::path(...)]`-annotated handler across the 19 files
in that module:

- Inserted a blank `///` line after the first short sentence/clause so
  utoipa's split produces a real summary + description, where the doc
  comment had more to say. Left already-short single-clause docs alone
  (nothing to split).
- Where a query struct derives `IntoParams`, moved param prose that
  duplicated a field's own doc comment out of the handler doc (the
  field already documents itself in the generated spec), or added a
  field doc where the handler explained a param that had none.

No behavior changes — doc comments and `params()` description text
only. Verified `cargo build -p hive-c0re` (clean) and `nix fmt` (zero
changes) after.

Closes #2969
This commit is contained in:
iris 2026-08-02 20:50:07 +02:00 • committed by mara
commit 071dbd774c
16 changed files with 193 additions and 133 deletions
Download patch file Download diff file Expand all files Collapse all files

68
hive-c0re/src/dashboard/schedules.rs
View file

@ -19,8 +19,10 @@ use crate::scheduled_prompts_worker::FireNowReport;
use super::{AppState, error_problem, error_response};
/// `GET /api/schedules` — snapshot of every schedule for the
/// scheduled-prompts tab. Returns the wire shape directly
/// so the frontend can render without an extra translation layer.
/// scheduled-prompts tab.
///
/// Returns the wire shape directly so the frontend can render
/// without an extra translation layer.
// `hive_sh4re::WireSchedule` (the actual body) has no `ToSchema` — adding
// one would pull `utoipa` into the wire-types crate for a single dashboard
// endpoint. `serde_json::Value` placeholder; see the batch report.
@ -58,10 +60,11 @@ pub(super) async fn api_schedules(State(state): State<AppState>) -> Response {
}
/// `POST /api/schedules` — operator-direct schedule creation
/// (mara: "user can add them manually"). Accepts the same
/// `SchedulePromptPayload` shape as the manager request flow but
/// skips the approval gate — the operator click *is* the
/// approval. The schedule lands directly with
/// (mara: "user can add them manually").
///
/// Accepts the same `SchedulePromptPayload` shape as the manager
/// request flow but skips the approval gate — the operator click
/// *is* the approval. The schedule lands directly with
/// `source = Operator` and the worker picks it up at fire time.
#[utoipa::path(
post,
@ -120,13 +123,15 @@ pub(super) struct FireNowBody {
}
/// `POST /api/schedules/{id}/fire-now` — operator-initiated
/// out-of-band fire of a scheduled prompt. Runs the per-target
/// fan-out once immediately and reports per-target outcome counts.
/// One-shot schedules are consumed (cancelled) by a manual fire —
/// the operator's intent is "send this now, the scheduled time was
/// wrong." For recurring schedules the cadence stays intact unless
/// the body carries `{"reset_timer": true}`, in which case the
/// countdown is re-armed from now (`next_fire_at = now + interval`).
/// out-of-band fire of a scheduled prompt.
///
/// Runs the per-target fan-out once immediately and reports
/// per-target outcome counts. One-shot schedules are consumed
/// (cancelled) by a manual fire — the operator's intent is "send
/// this now, the scheduled time was wrong." For recurring schedules
/// the cadence stays intact unless the body carries
/// `{"reset_timer": true}`, in which case the countdown is re-armed
/// from now (`next_fire_at = now + interval`).
#[utoipa::path(
post,
path = "/api/schedules/{id}/fire-now",
@ -244,17 +249,19 @@ where
}
/// `PATCH /api/schedules/{id}` — partial update of an existing
/// schedule. Mutable fields: `body`, `description`,
/// `interval_seconds`, `next_fire_at_unix`, plus the target set
/// via `targets_add` / `targets_remove`. Both target lists
/// are applied in the same transaction as the scalar fields with
/// removes-before-adds; re-adding a previously-removed target
/// resets per-target history (fresh start); draining all targets
/// auto-cancels the parent schedule. JSON body uses missing-key
/// = "leave alone", explicit null = "clear" for `description` +
/// `interval_seconds`. Cancelled schedules are refused — submit
/// a new one instead. Returns the updated `WireSchedule` so the
/// caller's post-edit refresh has the new state inline.
/// schedule.
///
/// Mutable fields: `body`, `description`, `interval_seconds`,
/// `next_fire_at_unix`, plus the target set via `targets_add` /
/// `targets_remove`. Both target lists are applied in the same
/// transaction as the scalar fields with removes-before-adds;
/// re-adding a previously-removed target resets per-target history
/// (fresh start); draining all targets auto-cancels the parent
/// schedule. JSON body uses missing-key = "leave alone", explicit
/// null = "clear" for `description` + `interval_seconds`. Cancelled
/// schedules are refused — submit a new one instead. Returns the
/// updated `WireSchedule` so the caller's post-edit refresh has the
/// new state inline.
#[utoipa::path(
patch,
path = "/api/schedules/{id}",
@ -293,8 +300,10 @@ pub(super) async fn patch_schedule(
}
/// `POST /api/schedules/{id}/pause` — pause a schedule so the worker
/// skips it until explicitly resumed. Idempotent; no-op on an already-
/// paused row. Returns 404 when the schedule is cancelled or not found.
/// skips it until explicitly resumed.
///
/// Idempotent; no-op on an already-paused row. Returns 404 when the
/// schedule is cancelled or not found.
#[utoipa::path(
post,
path = "/api/schedules/{id}/pause",
@ -326,6 +335,7 @@ pub(super) async fn post_schedule_pause(
}
/// `POST /api/schedules/{id}/resume` — resume a paused schedule.
///
/// Idempotent; no-op on an already-active row. Returns 404 when the
/// schedule is cancelled or not found.
#[utoipa::path(
@ -360,8 +370,10 @@ pub(super) async fn post_schedule_resume(
/// `POST /api/schedules/{id}/cancel` — operator-side cancel
/// (whole schedule when no `targets` field, partial when one is
/// provided). Operator bypasses the topology check; the manager
/// surface enforces it for agent callers.
/// provided).
///
/// Operator bypasses the topology check; the manager surface
/// enforces it for agent callers.
#[utoipa::path(
post,
path = "/api/schedules/{id}/cancel",