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
|
|
@ -104,7 +104,9 @@ fn account_name_from_filename(fname: &str) -> Option<String> {
|
|||
}
|
||||
|
||||
/// `GET /api/matrix-accounts?agent=<name>` — matrix accounts provisioned
|
||||
/// for `agent`, backfilled with `homeserver`/`live`/`user_id` from the daemon's
|
||||
/// for `agent`.
|
||||
///
|
||||
/// Backfilled with `homeserver`/`live`/`user_id` from the daemon's
|
||||
/// snapshot.
|
||||
#[utoipa::path(
|
||||
get,
|
||||
|
|
@ -188,6 +190,7 @@ struct MatrixLoginResult {
|
|||
}
|
||||
|
||||
/// Provision (or refresh) the token for an agent's extra matrix account.
|
||||
///
|
||||
/// password mode → `m.login.password`; token mode → validate via `whoami`.
|
||||
/// On success writes the token to `matrix-token-<account>` via hive-priv and
|
||||
/// kicks the daemon. Operator-authenticated (dashboard). Never echoes the
|
||||
|
|
@ -293,7 +296,9 @@ struct GithubAccountResult {
|
|||
}
|
||||
|
||||
/// Provision (or refresh) an agent's GitHub PAT from the dashboard
|
||||
/// credentials tab. Validates the agent name, then writes the PAT to
|
||||
/// credentials tab.
|
||||
///
|
||||
/// Validates the agent name, then writes the PAT to
|
||||
/// `<state>/github-token` (`0600`, agent-owned) via hive-priv. No account
|
||||
/// creation and no daemon to kick — the agent's `gh` wrapper / git credential
|
||||
/// helper read the file live, so the new token takes effect immediately.
|
||||
|
|
@ -339,9 +344,10 @@ struct GithubAccountStatus {
|
|||
}
|
||||
|
||||
/// `GET /api/github-account?agent=<name>` — whether the agent has a GitHub
|
||||
/// PAT provisioned (its `github-token` file exists). Lets the credentials tab
|
||||
/// show "token stored" vs "not set" instead of a black-hole paste field.
|
||||
/// Never returns the token itself.
|
||||
/// PAT provisioned (its `github-token` file exists).
|
||||
///
|
||||
/// Lets the credentials tab show "token stored" vs "not set" instead of a
|
||||
/// black-hole paste field. Never returns the token itself.
|
||||
#[utoipa::path(
|
||||
get,
|
||||
path = "/api/github-account",
|
||||
|
|
|
|||
Loading…
Reference in a new issue