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

8.0 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.

  • 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.

  • 2026-10-20: G3 Serving and CLI. document(peers) now returns a cached Arc<OpenApi> (one OnceLock per mode; generation walks every DTO and the whole tool router, and the result cannot change while the process runs), with build/to_pretty_json behind it so one function is shared by every consumer. GET /api/v1/openapi.json is mounted in api::router, i.e. under /api/v1 and therefore behind the existing auth layer; no new public route, no change to server::build_router or /healthz. It serves the mode of the running instance (state.peers.is_some()), so a peer-less instance advertises no peer paths. New slinuxm openapi [--peers] (src/cli.rs, Command::Openapi) prints the pretty document; main returns before Config::load, so it needs no config file, no token file and no socket and cannot start a server or bind a port. --print-config still wins if combined. The peers::cli import in main.rs is now aliased to peer_cli because cli is the new module.

    Tests: render_is_valid_json_for_both_modes, generation_is_deterministic (bytes, not just values, because the committed file is compared) in the unit tests; openapi_route_is_authenticated_and_serves_the_document (401 without a token, 200 with one, body equals the generated peers-on document, application/json) and cli_prints_the_same_document_offline (real binary, --config /nonexistent/..., both modes, output equals the generated document) in tests/openapi.rs.