feat: add OpenAPI 3.1 document generation and runtime API explorer

[dardevelin]

Summary

Adds a machine-generated OpenAPI 3.1 specification and wires it into the existing custom api.html explorer, replacing the previous hardcoded endpoint list with a dynamic, spec-driven UI. The visual design of api.html is fully preserved.

---

What changed

src/openapi.rs (new)

Full OpenAPI 3.1 document builder covering every route, controlled by a DocMode enum:

Mode	Included routes
Primary	All routes — ingest, mutations, proofs, sync/register, reconcile
Readonly	Read-only subset — omits all write and sync endpoints

Public surface: primary_document() / readonly_document() returning utoipa::openapi::OpenApi.

src/bin/gen_openapi.rs (new)

Standalone binary that prints the spec to stdout. Useful for CI artifact generation and the local preview workflow.

cargo run --bin gen_openapi              # primary spec
cargo run --bin gen_openapi -- --readonly

src/api.rs

Three new routes added to both build_router and build_readonly_router:

Route	Description
GET /api	Serves the themed HTML explorer
GET /api.html	Alias
GET /openapi.json	Serves the appropriate spec as JSON

src/lib.rs

• pub mod openapi declaration

Cargo.toml

Added utoipa = "5" for OpenAPI types and JSON serialisation. No proc-macro annotations are used anywhere — the spec is built as serde_json::Value and deserialised into utoipa::openapi::OpenApi, keeping the diff minimal.

tests/api_docs_tests.rs (new)

Three integration tests:

• api_explorer_html_is_served — correct content-type and body
• primary_spec_has_expected_paths — /ingest/feed present, security schemes defined
• readonly_spec_excludes_write_paths — /sync/register and PATCH routes absent

scripts/preview-docs.sh (new)

Helper that builds gen_openapi, dumps openapi.json, copies api.html, and serves both on port 8787 — opening the browser automatically.

./scripts/preview-docs.sh             # primary spec
./scripts/preview-docs.sh --readonly

---

Testing

cargo test                 # all tests pass
cargo clippy -- -D warnings  # clean
cargo fmt --check          # clean