Files
skyg-linux-tracker/plan/ws-g-openapi.md
T
2026-10-20 10:22:34 -04:00

2.4 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