docs: trim implementation detail from the OpenAPI/Swagger doc
mara, PR review: 'less impl details in user facing docs'. Dropped the utoipa crate link, the ApiDoc source-file pointer, and the #[utoipa::path(...)] annotation-syntax mention from the Dashboard endpoints intro paragraph -- kept only what a reader needs (where to find it, that it's a growing subset not yet the full list). Trimmed the H0M3-page mention the same way.
This commit is contained in:
parent
3f2fdeac70
commit
e6ecd8db60
1 changed files with 6 additions and 13 deletions
|
|
@ -722,9 +722,8 @@ The H0M3 hub is the primary landing page (served at `/` by default). A
|
|||
responsive grid of link tiles — Dashboard, Flow, Logs, Matrix (when enabled),
|
||||
Forge (when enabled), among others (Builds, Stats, Settings, Core,
|
||||
Credentials, API) — each pointing to their respective surfaces. The **API**
|
||||
tile is a static link straight to `/api/docs` (the Swagger UI — see
|
||||
`## Dashboard endpoints` below), always shown since the endpoint always
|
||||
exists (no gating, unlike Matrix/Forge). The page
|
||||
tile always shows (unlike Matrix/Forge, see below) and links to the
|
||||
Swagger UI at `/api/docs`. The page
|
||||
is a pure portal with no tab-bar or SSE subscriptions. Typography + colours
|
||||
inherit from the shared theme (Catppuccin Mocha via `common.css` + `theme.css`).
|
||||
Optional tiles are hidden until `home.js` confirms their availability:
|
||||
|
|
@ -1152,16 +1151,10 @@ that's a browser-level decision, not ours.
|
|||
|
||||
## Dashboard endpoints
|
||||
|
||||
Also browsable interactively: `hive-c0re` auto-generates an OpenAPI 3
|
||||
spec via [`utoipa`](https://docs.rs/utoipa) (`hive-c0re/src/dashboard/
|
||||
mod.rs`'s `ApiDoc`), served raw at `GET /api/openapi.json` and as a
|
||||
Swagger UI at `/api/docs` — same loopback dashboard port, reachable
|
||||
externally through the gateway's `/api/` proxy prefix like the rest of
|
||||
this list. It's deliberately incremental: only routes carrying a
|
||||
`#[utoipa::path(...)]` annotation appear, so it's not yet a complete
|
||||
mirror of the hand-written list below — an unannotated route still
|
||||
works, it just doesn't show up in the spec until someone adds the
|
||||
annotation. The H0M3 hub's **API** tile links straight to `/api/docs`.
|
||||
Also browsable interactively at `/api/docs` (a Swagger UI, linked from
|
||||
the H0M3 hub's **API** tile), with the raw spec at `/api/openapi.json`.
|
||||
It's a growing supplement, not yet a full replacement for the list
|
||||
below — some endpoints aren't in it yet.
|
||||
|
||||
- `POST /api/approve/{id}` — approve a pending approval. Fires
|
||||
`ApprovalResolved` on the dashboard event channel; client
|
||||
|
|
|
|||
Loading…
Reference in a new issue