Files
skyg-linux-tracker/plan/ws-g-openapi.md
T

5.2 KiB

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.