Files
zeekayandHanzo Dev 2b5d5d47ba feat(api): generate the published OpenAPI from the route table
The canonical spec (hanzoai/openapi, OpenAPI 3.1, "v1.0.0 locked in") is what
every SDK and the docs site are generated from — so it is what customers believe.
Hand-maintaining it beside a route table is two sources for one fact, and they
drift in the direction that hurts: the routes move, the spec does not, and nothing
fails.

This repo carried the proof. swagger/swagger.json documented `basePath: /api` with
135 `/<verb>-<noun>` paths — a base path this service has never served, wrong long
before the REST migration touched it, and no test ever noticed.

So the resource half of the spec is DERIVED from routers/resources.go:

    go run ./cmd/openapi -spec ../openapi/ai/openapi.yaml

routers.OpenAPIPaths is the one accessor over the same table that registers the
routes. 109 paths render into the region between the generated markers; the
inference paths above stay hand-authored, because their bodies are the OpenAI wire
format and no table can know them. Generation is for what repeats per-resource;
the shared envelope and error responses are constant, so they are written once by
hand. That is where the boundary belongs.

Three things the generator has to get right, each of which would otherwise ship a
spec that validates and lies:

  - The router spells a parameter `:owner`; OpenAPI spells it `{owner}`. Left in
    the router's spelling it validates fine and produces SDKs that request a
    literal ":owner".
  - A member is TWO path parameters, because identity here is the pair
    (owner, name) and one segment cannot carry it — an encoded composite is
    decoded back to a separator before routing and matches nothing.
  - PATCH and PUT reach ONE handler, so they need DISTINCT operationIds. A
    duplicate makes a generator emit one method name twice, and most keep only
    the last, silently.

The 200 description says outright that `status`, not the status line, is the
outcome — a handled failure is HTTP 200 with `status: error`. A client that
branches on the status code alone is wrong, and the spec now says so.

Six tests hold it: the spec matches the table (skipped when the sibling checkout
is absent, so it never becomes the test everyone turns off); rendering is
deterministic across runs, because a renderer leaking Go's map order would make
the drift check fail at random and get dismissed as flaky; the hand-authored half
survives regeneration byte-for-byte; a spec with no markers is refused rather than
clobbered; operationIds are unique; every path is OpenAPI-shaped. Verified by
adding a resource and watching the drift check fail, then reverting.

swagger/ is deleted — 3.8 MB of vendored swagger-ui and the wrong description.
Nothing shipped it, nothing embedded it, nothing referenced it.

Redocly validates the result. vet clean; the 8 pre-existing failures unchanged.

Co-authored-by: Hanzo Dev <[email protected]>
2026-07-27 08:30:01 -07:00
..