# 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