36 lines
6.5 KiB
Markdown
36 lines
6.5 KiB
Markdown
# WS-G: Generated OpenAPI documentation
|
|
|
|
Stand-alone workstream, not part of Phase 5. Request: an autogenerated OpenAPI doc for the REST API and the MCP server.
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Status | Not started |
|
|
| Owner | goose |
|
|
| Depends on | Phase 5 routes and tools on main (peer routes are part of the spec) |
|
|
| Owned files | `src/openapi.rs`, `src/api/**`, `src/mcp/**`, `src/main.rs`, `src/lib.rs`, `src/cli.rs`, `Cargo.toml`, `tests/openapi.rs`, `docs/openapi.json`, `docs/api.md`, `README.md`, `config.example.toml`, `TODO.md` is NOT owned (merger ticks) |
|
|
|
|
## Tasks
|
|
|
|
1. **G1 REST spec.** Add `utoipa` (check that `cargo tree -i openssl` stays empty). Derive `ToSchema` on the response DTOs and annotate every REST handler with `#[utoipa::path]` (systemd, journal, docker, tokens-free endpoints, `/healthz`, `/api/v1/ping`, peers status and the peer proxy as one documented wildcard `GET /api/v1/peers/{peer}/{path}` listing the allowlist). Declare the bearer security scheme. Single `ApiDoc` in `src/openapi.rs`. The peer paths appear only when peers are enabled, matching the real router.
|
|
2. **G2 MCP description.** MCP is JSON-RPC, so it cannot be modelled as paths. Document `POST /mcp` (Streamable HTTP) in the same spec and add a vendor extension `x-mcp-tools` listing every tool with its description and input JSON Schema, generated from the rmcp tool router (the schemars schemas it already holds), not hand-written. Tool count is 8, or 10 with peers; the existing snapshot test must still pass.
|
|
3. **G3 Serving and CLI.** `GET /api/v1/openapi.json` behind the normal auth (no new public route), and `slinuxm openapi [--peers]` printing the spec offline without starting the server or reading any token. Keep the spec generation in one function shared by both.
|
|
4. **G4 Drift guard and docs.** Commit the generated `docs/openapi.json` (peers on). `tests/openapi.rs` regenerates it and fails with the regeneration command if it differs; also validates structure (every route in the real router is documented, every tool in the tool router appears in `x-mcp-tools`, so an undocumented new route or tool fails a test). Update `docs/api.md` and `README.md` briefly.
|
|
|
|
## Rules
|
|
|
|
Reuse existing DTOs, do not duplicate types for the doc. Read-only, no secrets in the spec or examples. Surfaces call `sources/`, do not touch D-Bus or Docker from the doc code. Tests in the same commit as the code. No workstream tags in comments.
|
|
|
|
## Log
|
|
|
|
- 2026-10-20: **G1 REST spec.** `utoipa` 6.0.0 (default features, macros included) added to `Cargo.toml`; `cargo tree -i openssl` is still empty. Every REST handler carries `#[utoipa::path]` with an explicit `operationId`, tag, params and the real response set (200 body plus 400/401/404/405/503 `ErrorBody` where they exist); handlers became `pub(crate)` so the `ApiDoc` derive in `src/openapi.rs` can name them. One `ApiDoc` plus one `document(peers: bool)` function; the bearer scheme is declared once (`bearer_auth`) and applied globally, with `/healthz` opting out via `security(())`. Peer paths are dropped when `peers` is false, matching the router (`paths.retain`). The peer pass-through is documented as one wildcard operation `GET /api/v1/peers/{peer}/{path}` whose description lists the allowlist.
|
|
|
|
**Owned-files conflict with G1 as written.** G1 says "derive `ToSchema` on the response DTOs", but those DTOs live in `src/sources/mod.rs` and `src/peers/types.rs`, which are not in this workstream's owned files, so no derive could be added there. Resolution, inside `src/openapi.rs` only: the DTOs already derive `schemars::JsonSchema` for MCP, so a small bridge (`reflected<T>()` + a `PartialSchema`/`ToSchema` impl macro) reflects each component from the schemars schema of the same type. There is exactly one definition per DTO and a field added to a DTO shows up in the spec with no edit here. `peer_status_components...`-style payloads that exist only as JSON (error body, `/healthz` and `/api/v1/ping` body) or have no schemars derive (`PeerStatus`, `ServerStatus`, `ApiStatus`, `AuthState` from `src/peers/types.rs`) are described by hand with utoipa builders and checked against the JSON the server really emits (`error_body_and_health_match_the_real_payloads`, `peer_status_components_cover_the_serialized_fields`), so an added field fails a test instead of vanishing from the document. `reflected_schemas_match_schemars` asserts the reflected component equals the schemars output exactly, which pins the converter (object/array/oneOf/anyOf/allOf/format/enum/default/minimum/maximum/required/properties).
|
|
|
|
Translation note for a future merger: if WS-G is ever allowed to touch the DTO files, the derive can replace the bridge for `src/sources/mod.rs`; the peer types would still need `JsonSchema` added.
|
|
|
|
Tests: 10 unit tests in `src/openapi.rs` (reflection parity, payload parity, peer gating, operation ids and 2xx, bearer scheme, determinism) and `tests/openapi.rs` with the router drift guard started here (source scan of every `.route(...)` literal in `src/api/**` plus `src/server.rs`, `/api/v1` prefix applied as `server.rs` nests it, axum `{*path}` normalised to OpenAPI `{path}`, and one request per documented path that must not hit the fallback's `no such route`). `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings` and `cargo test` green.
|
|
|
|
- 2026-10-20: **G2 MCP description.** MCP is JSON-RPC, so it is documented as one operation `POST /mcp` (declared on a doc-only `mcp_endpoint()` in `src/openapi.rs`; the real handler is rmcp's `StreamableHttpService`, which has no axum handler fn to annotate) with the request body, the `application/json` + `text/event-stream` response, and the 400/401/403/404/406/415 codes rmcp and the auth layer really return. `x-mcp-tools` is generated from the tool router itself: `TrackerService::advertised_tools(peers)` builds the same `ToolRouter` that `TrackerService::new` stores (extracted into `router_for`, so there is one place that applies the peer gating) and returns `name`, `description` and `input_schema` for every tool, sorted, so the extension cannot drift from `tools/list`. Tool count stays 8 without peers and 10 with them; the existing peers-off snapshot test is untouched and still passes.
|
|
|
|
Tests: `mcp_endpoint_is_documented_in_both_modes` and `mcp_extension_lists_tools_sorted_with_schemas` in `src/openapi.rs`; `mcp_tools_match_the_tool_router` (every entry equal to the router's name/description/input schema, both modes), `mcp_tool_count_follows_the_peers_flag` and the `/mcp` mount added to the route scan in `tests/openapi.rs`. `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings` and `cargo test` green.
|