11 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. -
2026-10-20: G4 Drift guard and docs.
docs/openapi.jsonis committed (peers on, pretty-printed byslinuxm openapi --peers, 15 paths and 10 tools).tests/openapi.rsnow holds the guards:committed_spec_matches_the_codecompares the file byte for byte withcli::render(true)and prints the regeneration command (cargo run -- openapi --peers > docs/openapi.json) on failure;every_router_route_is_documentedscans every.route(...)literal insrc/api/**andsrc/server.rsplus the/mcpmount and requires each path in the document (verified by adding a throwaway route: the test failed with/api/v1/ping/extra is routed but missing from the OpenAPI document);every_documented_path_is_routedsends one request per documented path through the assembled router and fails if it hits the fallback'sno such route;mcp_tools_match_the_tool_routerrequires every tool of the router inx-mcp-toolswith the same description and input schema (a new or gated-off tool changes the spec and then fails the staleness check);every_operation_is_read_onlykeeps every operation a GET exceptPOST /mcp;operation_ids_and_tags_are_declaredcatches duplicate ids and undeclared tags. A crate version bump changesinfo.version, so it also needs the regeneration in the same commit; that is deliberate (the file is the artifact that is published).Docs:
docs/api.mdgains a "Generated reference (OpenAPI)" section (what the file contains,GET /api/v1/openapi.json,slinuxm openapi [--peers], regeneration, what the tests guard) and a route-table row;README.mdgets a short paragraph in the REST section.config.example.tomlneeds nothing (no new key).docs/README.mddoes not listdocs/openapi.jsonyet; it is outside this workstream's owned files, so the merger should add the row.Verification:
cargo fmt --check,cargo clippy --all-targets -- -D warnings,cargo testgreen (10 tests intests/openapi.rs, 12 unit tests insrc/openapi.rs/src/cli.rs);cargo tree -i opensslempty; the committed spec contains no token, token-file path or URL other than the documented default server. No nix build was run; no VM test is involved in this workstream. -
2026-10-20: G4 self-review fixes. Three accuracy gaps found on a second read: the
ErrorBody.codeenum listed only theAppErrorcodes, but two status-only bodies reuseerror_response(method_not_allowedfrom the 405 fallback,forbidden_hostfrom the auth-off Host guard), so both are now documented andevery_error_code_is_documentedties the enum toAppError::code()plus those two; the dockerlogsand the peer pass-through 200s now declare bothapplication/jsonandtext/event-streaminstead of JSON only;schema_typeno longer maps an unknown JSON Schema type name toobject(it leaves the type out), so the converter cannot invent a type the DTO does not have. Spec regenerated.