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

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

View file

@ -34,6 +34,7 @@ pub(super) struct JournalQuery {
}
/// Read `journalctl -M <container> -b` and return its text output.
///
/// Operator-only by virtue of the dashboard being host-bound. hive-c0re
/// runs unprivileged (privsep), so the `-M` read — which enters the
/// container namespace and needs root — is delegated to hive-priv.
@ -160,9 +161,11 @@ pub(super) struct JournalHostQuery {
}
/// `GET /api/journal-host?unit=<unit>&lines=N` — host-side journald (no
/// `-M` container flag). Restricted to an allow-list of known host services
/// so arbitrary unit names can't be probed. Operator-only by virtue of the
/// dashboard binding to a host-only port.
/// `-M` container flag).
///
/// Restricted to an allow-list of known host services so arbitrary unit
/// names can't be probed. Operator-only by virtue of the dashboard binding
/// to a host-only port.
#[utoipa::path(
get,
path = "/api/journal-host",