From 38f1bf99fcbbdfb5c01394f6e97c557e449cb05d Mon Sep 17 00:00:00 2001 From: ari Date: Tue, 20 Oct 2026 10:22:34 -0400 Subject: [PATCH] Plan WS-G: generated OpenAPI doc Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_019dpKwZWtahQU4V2NhpVmLt --- plan/ws-g-openapi.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 plan/ws-g-openapi.md diff --git a/plan/ws-g-openapi.md b/plan/ws-g-openapi.md new file mode 100644 index 0000000..bb6aa3b --- /dev/null +++ b/plan/ws-g-openapi.md @@ -0,0 +1,23 @@ +# 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