Publish an HTTP API/OpenAPI reference for `httpapi.NewMux`

[devblac]

Publish an HTTP API/OpenAPI reference for httpapi.NewMux

 

Context

While building a small client, I had to dig through handler code to learn the REST/WebSocket routes, params, and error shapes. There’s no reference doc, so every new consumer repeats the same spelunking.
 

Problem

Routes, query params, and error payloads are only discoverable by reading httpapi.NewMux and handlers. There’s no OpenAPI spec or even basic curl examples.
 

Expected behavior

A checked-in OpenAPI spec describes the current HTTP/WebSocket endpoints, and a short doc shows example curl calls for points, badges, health, and subscriptions.
 

Scope / non-goals

Don’t invent new endpoints or error shapes; just document what exists today. No need to wire up CI validation unless it’s trivial.
 

Acceptance criteria

• OpenAPI spec (YAML/JSON) lives under docs/ and matches the current routes and response shapes, including errors.
• Doc or README section links to the spec and includes example curl calls for points, badges, health, and WebSocket subscription.
• Spec generation/validation step is optional; if added, note how to run it.
   

Hints

Look at httpapi.NewMux for routes and handler structs for request/response bodies. Place the spec under docs/ (e.g., docs/openapi.yaml).