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

15
hive-c0re/src/dashboard/infra_containers.rs
View file

@ -15,13 +15,14 @@ use hive_priv_sock::{InfraAction, InfraContainer};
use super::{AppState, error_response};
/// `POST /api/infra-container/{name}/{action}` — start / stop / restart a
/// hive infrastructure container from the dashboard. `name` parses into
/// [`InfraContainer`] (the allowlist; unrecognised names 400), `action`
/// into `start` / `stop` / `restart`. Every attempt lands in the audit log
/// (actor `"operator"`, action `start_infra` / `stop_infra` /
/// `restart_infra`) and streams as an `AuditEntryAdded` event, so
/// operator-driven and agent-driven (`infra_admin`) infra actions show up
/// in the same AUDIT view.
/// hive infrastructure container from the dashboard.
///
/// `name` parses into [`InfraContainer`] (the allowlist; unrecognised
/// names 400), `action` into `start` / `stop` / `restart`. Every attempt
/// lands in the audit log (actor `"operator"`, action `start_infra` /
/// `stop_infra` / `restart_infra`) and streams as an `AuditEntryAdded`
/// event, so operator-driven and agent-driven (`infra_admin`) infra
/// actions show up in the same AUDIT view.
#[utoipa::path(
post,
path = "/api/infra-container/{name}/{action}",