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

18
hive-c0re/src/dashboard/extra_forges.rs
View file

@ -58,11 +58,13 @@ pub(super) struct ExtraForgesQuery {
agent: String,
}
/// `GET /api/extra-forges?agent=<name>` — list the external forge accounts
/// currently provisioned for `agent`, derived from every `forge-<label>-
/// 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.
/// `GET /api/extra-forges?agent=<name>` — list the external forge
/// accounts currently provisioned for `agent`.
///
/// Derived from every `forge-<label>-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",
@ -135,8 +137,10 @@ struct ExtraForgeAccountResult {
/// `POST /api/extra-forge-account` — add persists the operator-pasted
/// label/base-URL/token to the agent's state dir via hive-priv; remove
/// deletes both files. Purely local — no remote account creation or
/// revocation, there is no admin access assumed on the external forge.
/// 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,