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:
parent
c5fe61777e
commit
071dbd774c
16 changed files with 193 additions and 133 deletions
|
|
@ -60,7 +60,9 @@ pub(super) async fn post_rebuild(
|
|||
}
|
||||
|
||||
/// `POST /api/kill/{name}?graceful=1` — stop `name`, hard by default or
|
||||
/// gracefully (quiesce → drain → stop) when `graceful=1`.
|
||||
/// gracefully when `graceful=1`.
|
||||
///
|
||||
/// Graceful mode: quiesce → drain → stop.
|
||||
#[utoipa::path(
|
||||
post,
|
||||
path = "/api/kill/{name}",
|
||||
|
|
@ -120,7 +122,9 @@ pub(super) async fn post_kill(
|
|||
}
|
||||
|
||||
/// `POST /api/restart/{name}?graceful=1` — restart `name`, hard by default
|
||||
/// or gracefully (quiesce → drain → restart) when `graceful=1`.
|
||||
/// or gracefully when `graceful=1`.
|
||||
///
|
||||
/// Graceful mode: quiesce → drain → restart.
|
||||
#[utoipa::path(
|
||||
post,
|
||||
path = "/api/restart/{name}",
|
||||
|
|
@ -423,9 +427,10 @@ pub(super) struct DestroyForm {
|
|||
purge: Option<String>,
|
||||
}
|
||||
|
||||
/// `POST /api/destroy/{name}` — destroy `name`'s container. Form field
|
||||
/// `purge` (any non-empty value, e.g. `"on"`) also wipes the retained
|
||||
/// state dir instead of leaving a tombstone.
|
||||
/// `POST /api/destroy/{name}` — destroy `name`'s container.
|
||||
///
|
||||
/// Form field `purge` (any non-empty value, e.g. `"on"`) also wipes the
|
||||
/// retained state dir instead of leaving a tombstone.
|
||||
#[utoipa::path(
|
||||
post,
|
||||
path = "/api/destroy/{name}",
|
||||
|
|
|
|||
Loading…
Reference in a new issue