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
- G1 REST spec. Add
utoipa(check thatcargo tree -i opensslstays empty). DeriveToSchemaon 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 wildcardGET /api/v1/peers/{peer}/{path}listing the allowlist). Declare the bearer security scheme. SingleApiDocinsrc/openapi.rs. The peer paths appear only when peers are enabled, matching the real router. - 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 extensionx-mcp-toolslisting 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. - G3 Serving and CLI.
GET /api/v1/openapi.jsonbehind the normal auth (no new public route), andslinuxm openapi [--peers]printing the spec offline without starting the server or reading any token. Keep the spec generation in one function shared by both. - G4 Drift guard and docs. Commit the generated
docs/openapi.json(peers on).tests/openapi.rsregenerates 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 inx-mcp-tools, so an undocumented new route or tool fails a test). Updatedocs/api.mdandREADME.mdbriefly.
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.
utoipa6.0.0 (default features, macros included) added toCargo.toml;cargo tree -i opensslis still empty. Every REST handler carries#[utoipa::path]with an explicitoperationId, tag, params and the real response set (200 body plus 400/401/404/405/503ErrorBodywhere they exist); handlers becamepub(crate)so theApiDocderive insrc/openapi.rscan name them. OneApiDocplus onedocument(peers: bool)function; the bearer scheme is declared once (bearer_auth) and applied globally, with/healthzopting out viasecurity(()). Peer paths are dropped whenpeersis false, matching the router (paths.retain). The peer pass-through is documented as one wildcard operationGET /api/v1/peers/{peer}/{path}whose description lists the allowlist.Owned-files conflict with G1 as written. G1 says "derive
ToSchemaon the response DTOs", but those DTOs live insrc/sources/mod.rsandsrc/peers/types.rs, which are not in this workstream's owned files, so no derive could be added there. Resolution, insidesrc/openapi.rsonly: the DTOs already deriveschemars::JsonSchemafor MCP, so a small bridge (reflected<T>()+ aPartialSchema/ToSchemaimpl 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,/healthzand/api/v1/pingbody) or have no schemars derive (PeerStatus,ServerStatus,ApiStatus,AuthStatefromsrc/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_schemarsasserts 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 needJsonSchemaadded.Tests: 10 unit tests in
src/openapi.rs(reflection parity, payload parity, peer gating, operation ids and 2xx, bearer scheme, determinism) andtests/openapi.rswith the router drift guard started here (source scan of every.route(...)literal insrc/api/**plussrc/server.rs,/api/v1prefix applied asserver.rsnests it, axum{*path}normalised to OpenAPI{path}, and one request per documented path that must not hit the fallback'sno such route).cargo fmt --check,cargo clippy --all-targets -- -D warningsandcargo testgreen. -
2026-10-20: G2 MCP description. MCP is JSON-RPC, so it is documented as one operation
POST /mcp(declared on a doc-onlymcp_endpoint()insrc/openapi.rs; the real handler is rmcp'sStreamableHttpService, which has no axum handler fn to annotate) with the request body, theapplication/json+text/event-streamresponse, and the 400/401/403/404/406/415 codes rmcp and the auth layer really return.x-mcp-toolsis generated from the tool router itself:TrackerService::advertised_tools(peers)builds the sameToolRouterthatTrackerService::newstores (extracted intorouter_for, so there is one place that applies the peer gating) and returnsname,descriptionandinput_schemafor every tool, sorted, so the extension cannot drift fromtools/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_modesandmcp_extension_lists_tools_sorted_with_schemasinsrc/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_flagand the/mcpmount added to the route scan intests/openapi.rs.cargo fmt --check,cargo clippy --all-targets -- -D warningsandcargo testgreen. -
2026-10-20: G3 Serving and CLI.
document(peers)now returns a cachedArc<OpenApi>(oneOnceLockper mode; generation walks every DTO and the whole tool router, and the result cannot change while the process runs), withbuild/to_pretty_jsonbehind it so one function is shared by every consumer.GET /api/v1/openapi.jsonis mounted inapi::router, i.e. under/api/v1and therefore behind the existing auth layer; no new public route, no change toserver::build_routeror/healthz. It serves the mode of the running instance (state.peers.is_some()), so a peer-less instance advertises no peer paths. Newslinuxm openapi [--peers](src/cli.rs,Command::Openapi) prints the pretty document;mainreturns beforeConfig::load, so it needs no config file, no token file and no socket and cannot start a server or bind a port.--print-configstill wins if combined. Thepeers::cliimport inmain.rsis now aliased topeer_clibecausecliis 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) andcli_prints_the_same_document_offline(real binary,--config /nonexistent/..., both modes, output equals the generated document) intests/openapi.rs.