Compare commits

...
Author SHA1 Message Date
iris
e6ecd8db60 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.
2026-08-02 19:13:41 +02:00
iris
3f2fdeac70 docs: document the OpenAPI spec + Swagger UI, add H0M3 API tile
Closes #2965.

hive-c0re auto-generates an OpenAPI 3 spec via utoipa
(hive-c0re/src/dashboard/mod.rs's ApiDoc), served raw at
/api/openapi.json and browsable as a Swagger UI at /api/docs, but
docs/ never mentioned either — genuinely zero hits grepping the whole
docs/ tree. Documented both in docs/web-ui/dashboard.md's Dashboard
endpoints + H0M3 page sections.

Also added the H0M3 hub's API tile mara suggested ("maybe also add
home page app that opens swagger ui") -- a plain static link to
/api/docs, no gating needed since the endpoint always exists
(unlike Forge/Matrix, which are conditionally enabled).
2026-08-02 19:13:41 +02:00
2 changed files with 20 additions and 1 deletions

View file

@ -720,7 +720,10 @@ re-renders the terminal row. The root agent is addressed as `@root`.
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) — each pointing to their respective surfaces. The page
Forge (when enabled), among others (Builds, Stats, Settings, Core,
Credentials, API) — each pointing to their respective surfaces. The **API**
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:
@ -1148,6 +1151,11 @@ that's a browser-level decision, not ours.
## Dashboard endpoints
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
updates derived approvals state from the event.

View file

@ -100,6 +100,17 @@
<span class="home-tile-desc">provision per-agent matrix + github accounts</span>
</a>
<!-- API tile: no gating, unlike Forge/Matrix below — the OpenAPI
spec + Swagger UI are always served by hive-c0re itself
(docs/web-ui/dashboard.md::Dashboard endpoints). -->
<a class="home-tile" href="/api/docs">
<span class="home-tile-head">
<span class="home-tile-icon" aria-hidden="true">🧬</span>
<span class="home-tile-label">API</span>
</span>
<span class="home-tile-desc">interactive OpenAPI spec (Swagger UI)</span>
</a>
<!-- Forge tile: hidden until home.js confirms the hive-forge
container is up (state.forge_present); home.js also fills the
href from state.forge_public_url (or the :3000 fallback), so