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

26
hive-c0re/src/dashboard/permissions.rs
View file

@ -299,13 +299,14 @@ pub(super) struct BatchPermsBody {
/// `(logical agent, new groups?, new caps?)`.
type StagedPerm = (String, Option<Vec<String>>, Option<Vec<String>>);
/// Batch permission apply — `POST /api/permissions`. The save-all
/// permissions UI sends only the perm-types that actually changed per
/// agent; each affected agent gets ONE combined `PermChange`, so the
/// dedup key collapses to `(kind, agent)` and an agent whose caps AND
/// groups both changed rebuilds once, not twice. The whole batch is
/// atomic: every change is validated up front and on any validation
/// error nothing is written or enqueued.
/// Batch permission apply — `POST /api/permissions`.
///
/// The save-all permissions UI sends only the perm-types that actually
/// changed per agent; each affected agent gets ONE combined
/// `PermChange`, so the dedup key collapses to `(kind, agent)` and an
/// agent whose caps AND groups both changed rebuilds once, not twice.
/// The whole batch is atomic: every change is validated up front and
/// on any validation error nothing is written or enqueued.
#[utoipa::path(
post,
path = "/api/permissions",
@ -428,11 +429,12 @@ pub(super) async fn get_stale_permissions(
}
/// Clear all explicit permission entries for a named agent without
/// requiring it to exist in the live roster. Used by the P3RM1SS10NS
/// tab's "remove" button for agents that have stale explicit entries
/// in `tool-groups.json` / `capabilities.json` but are no longer
/// running (e.g. an agent that was renamed or destroyed while its
/// JSON entries persisted).
/// requiring it to exist in the live roster.
///
/// Used by the P3RM1SS10NS tab's "remove" button for agents that have
/// stale explicit entries in `tool-groups.json` / `capabilities.json`
/// but are no longer running (e.g. an agent that was renamed or
/// destroyed while its JSON entries persisted).
///
/// Bypasses `guard_agent_name`'s live-roster check intentionally —
/// the whole point is to remove entries for non-roster agents. Only