`cloud/openapi.yaml` was a hand-written contract for a product with five served
routes and 151 that answer `not found`. It is now a verbatim copy of hanzoai/cloud's
own woven document, pulled by `sync.py` from that repo's origin/main (34663c49).
Cloud regenerates that document from its router and fails its own build on any
diff, so it cannot describe a route the binary does not serve — the property no
spec here has — which is why `merge.py` merges it LAST and lets it WIN every
route an authored spec also claims (298), explicitly rather than by where
`cloud` falls in the alphabet.
The document that every SDK, doc site and tool generates from goes 1132 -> 1737
paths, 1519 -> 2478 operations, and 699 -> 1217 operations carrying a
description — prose lifted from the handlers' Go doc comments, not written
twice. `tags` and `x-tagGroups` now describe the tags OPERATIONS carry (263, of
which 213 described, cloud's being the owning package's synopsis) instead of the
55 spec directories, four of which any operation carried. The registry still
decides the movements: a tag's group is the domain of the service that
introduced it.
Three defects that reached generators are fixed where codegen identity already
lives. An operation with no `responses` (668, cloud's untyped routes) gets a
`default` saying exactly that, rather than a schema nobody knows. An operation
with no tag takes its service's name, rather than `DefaultApi`. And
`cloud_get_v1_pricing-policy` and `cloud_get_v1_pricing_policy` — two real
routes, distinct strings, one Go type once the generator strips punctuation —
are separated. openapi-generator 7.14.0: 0 errors, 0 warnings (was 35 errors,
68 warnings); go and typescript-axios both generate; the Go client compiles.
Six route collisions surfaced the moment the merge stopped resolving them by
alphabet, and every one was duplicate authoring. `/health` was declared by nine
specs and answers with the SPA at api.hanzo.ai, while `/healthz` answers JSON:
it is gateway's alone now. `observe`, `app` and `product` declared only other
services' routes — o11y's, projects', vector's and search-docs' — and are
collapsed. Every route they held is still in the document, from cloud.
`generated/hanzo.json` is deleted. Measuring hanzo.yaml against a document
hanzo.yaml now contains is tautology, and a second, older copy of one emission
is the drift this change exists to end.
`flows.yaml` is new: hello, chat, money, store, agent, tools — six journeys
naming the exact operationIds a client calls and what each step asserts, so
every SDK's examples are the SAME journeys. merge.py refuses to write the
document if a flow names an operation it does not have, and three flows record
a substitution where the obvious route is not the served one.
Co-authored-by: Hanzo Dev <[email protected]>
zeekayandHanzo Dev
1f93702023