G: G4 Drift guard and docs commit the spec and fail tests on drift

This commit is contained in:
ari committed 2026-10-20 15:54:13 -04:00
1 parent 869b6818e9
commit 34a1e1644c
5 files changed
+1986

No files matched your search

+13
View File
@@ -2,6 +2,18 @@
Full endpoint and MCP client reference. The short version is in the [README](../README.md); the design is in [ARCHITECTURE.md](../ARCHITECTURE.md#rest-api).
## Generated reference (OpenAPI)
[`openapi.json`](openapi.json) is a committed OpenAPI 3.1 description of everything this binary serves: every REST route with its parameters and response schemas, the error shape, `POST /mcp`, and an `x-mcp-tools` extension listing each MCP tool with the description and input JSON Schema the tool router reports (eight tools, or ten with `[peers] enabled = true`). `tests/openapi.rs` keeps it true: it fails if a route of the real router is undocumented, if a tool is missing from `x-mcp-tools`, or if the file is stale.
- `GET /api/v1/openapi.json` returns the document for the running instance, behind the same bearer token as the rest of `/api/v1`. Peer routes appear only when peers are enabled.
- `slinuxm openapi [--peers]` prints the same document offline: no config file, no token, no server, no port. `--peers` describes a consolidator; without it you get the peer-less instance.
- Regenerate after changing a route, a tool, a response type or the crate version:
```sh
cargo run -- openapi --peers > docs/openapi.json
```
## REST
Base: `http://127.0.0.1:1984`. Errors are `{"error":{"code","message"}}`.
@@ -20,6 +32,7 @@ Base: `http://127.0.0.1:1984`. Errors are `{"error":{"code","message"}}`.
| `GET /api/v1/peers` | consolidator only; sorted status list; absent when peers are disabled |
| `GET /api/v1/peers/{peer}` | one peer's status object; unknown name is 404 |
| `GET /api/v1/peers/{peer}/...` | GET-only pass-through of that peer's documented routes |
| `GET /api/v1/openapi.json` | this document, OpenAPI 3.1 (see [Generated reference](#generated-reference-openapi)) |
```sh
TOKEN=slinuxm_...