Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019dpKwZWtahQU4V2NhpVmLt
2.4 KiB
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
- 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.