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

163 lines
5.3 KiB
Go

// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// Command openapi renders the resource surface into the canonical spec.
//
// go run ./cmd/openapi -spec ../openapi/ai/openapi.yaml # write
// go run ./cmd/openapi -spec ../openapi/ai/openapi.yaml -verify # check only
//
// The canonical spec (hanzoai/openapi, OpenAPI 3.1, "v1.0.0 locked in") is the
// published contract every SDK and the docs site are generated from. The resource
// half of it is DERIVED from routers/resources.go — the same table that registers
// the routes — so the contract cannot describe a surface the service does not
// serve. That is the failure this replaces: the repo's swagger.json still
// documents `/api/<verb>-<noun>`, a base path nothing has ever served.
//
// Only the region between the generated markers is touched. The inference paths
// above it are hand-authored with real request/response schemas and stay that way:
// they are ten stable endpoints whose bodies are the OpenAI wire format, not
// something a table can know. Generation is for the part that repeats.
package main
import (
"flag"
"fmt"
"os"
"sort"
"strings"
yaml "go.yaml.in/yaml/v3"
"github.com/hanzoai/ai/routers"
)
const (
beginMarker = " # BEGIN generated: resource surface (go run ./cmd/openapi) — DO NOT EDIT BY HAND"
endMarker = " # END generated: resource surface"
)
func main() {
spec := flag.String("spec", "", "path to the canonical ai/openapi.yaml")
checkOnly := flag.Bool("verify", false, "exit non-zero if the spec is out of date; write nothing")
flag.Parse()
if *spec == "" {
fail("-spec is required (path to hanzoai/openapi ai/openapi.yaml)")
}
if err := routers.AssertOperationIDsUnique(); err != nil {
fail("refusing to render: %v", err)
}
current, err := os.ReadFile(*spec)
if err != nil {
fail("read spec: %v", err)
}
next, err := render(string(current))
if err != nil {
fail("%v", err)
}
if string(current) == next {
fmt.Fprintf(os.Stderr, "openapi: up to date (%d paths)\n", len(routers.OpenAPIPathsSorted()))
return
}
if *checkOnly {
fail("spec is OUT OF DATE — run: go run ./cmd/openapi -spec %s", *spec)
}
if err := os.WriteFile(*spec, []byte(next), 0o644); err != nil {
fail("write spec: %v", err)
}
fmt.Fprintf(os.Stderr, "openapi: wrote %d generated paths to %s\n", len(routers.OpenAPIPathsSorted()), *spec)
}
// render replaces the generated region with the freshly-rendered resource paths,
// leaving every other byte of the spec untouched.
func render(spec string) (string, error) {
begin := strings.Index(spec, beginMarker)
end := strings.Index(spec, endMarker)
if begin < 0 || end < 0 || end < begin {
return "", fmt.Errorf("spec has no generated region — add these two lines under `paths:`:\n%s\n%s", beginMarker, endMarker)
}
body, err := renderPaths()
if err != nil {
return "", err
}
return spec[:begin] + beginMarker + "\n" + body + spec[end:], nil
}
// renderPaths emits the path items as YAML at the two-space indent `paths:`
// entries sit at, in sorted order so the output is byte-stable across runs.
func renderPaths() (string, error) {
paths := routers.OpenAPIPaths()
keys := routers.OpenAPIPathsSorted()
var b strings.Builder
for _, k := range keys {
item, _ := paths[k].(map[string]any)
// Emit one path item at a time: yaml.Marshal of the whole map would sort
// keys its own way and lose the method ordering below.
node, err := ordered(item)
if err != nil {
return "", fmt.Errorf("encode %s: %w", k, err)
}
out, err := yaml.Marshal(map[string]*yaml.Node{k: node})
if err != nil {
return "", fmt.Errorf("marshal %s: %w", k, err)
}
for _, line := range strings.Split(strings.TrimRight(string(out), "\n"), "\n") {
b.WriteString(" " + line + "\n")
}
}
return b.String(), nil
}
// ordered returns the path item with its methods in conventional HTTP order, so a
// reader sees get before delete rather than alphabetical noise.
func ordered(item map[string]any) (*yaml.Node, error) {
order := []string{"get", "post", "put", "patch", "delete"}
rank := map[string]int{}
for i, m := range order {
rank[m] = i
}
keys := make([]string, 0, len(item))
for k := range item {
keys = append(keys, k)
}
sort.Slice(keys, func(i, j int) bool {
ri, oki := rank[keys[i]]
rj, okj := rank[keys[j]]
if oki && okj {
return ri < rj
}
return keys[i] < keys[j]
})
// yaml.v3 sorts a Go map's keys on encode, so the METHOD order has to be
// carried by an explicit mapping node rather than a map.
m := &yaml.Node{Kind: yaml.MappingNode}
for _, k := range keys {
v := &yaml.Node{}
if err := v.Encode(item[k]); err != nil {
return nil, err
}
m.Content = append(m.Content,
&yaml.Node{Kind: yaml.ScalarNode, Value: k}, v)
}
return m, nil
}
func fail(format string, a ...any) {
fmt.Fprintf(os.Stderr, "openapi: "+format+"\n", a...)
os.Exit(1)
}