openapi

type Components ¶ added in v1.801.299

type Components struct {
	Schemas map[string]any `json:"schemas,omitempty"`
}

Components holds the named schemas operations reference by $ref, so an SDK generator mints one named type per Go struct instead of an anonymous shape per operation. Open-typed: Register contributes *Schema values, the typed fold contributes zip's JSON Schema verbatim — both marshal to the same vocabulary.

type Conflict ¶ added in v1.801.299

type Conflict struct {
	Kind string // "operation" or "schema"
	Name string // "GET /v1/x" or the schema name
	A, B string // the two apps that claim it, in weave order
}

Conflict is two apps disagreeing about one name. Typed rather than a bare error string so a caller (and the gate) can assert on the KIND of collision without matching prose.

func (c *Conflict) Error() string

type Document ¶

type Document struct {
	OpenAPI    string              `json:"openapi"`
	Info       Info                `json:"info"`
	Servers    []Server            `json:"servers,omitempty"`
	Tags       []Tag               `json:"tags,omitempty"`
	Paths      map[string]PathItem `json:"paths"`
	Components *Components         `json:"components,omitempty"`
}

Document is an OpenAPI 3.1 document.

What IS derivable from the router, and what is NOT ¶

The router is a dispatch table: pattern → handler. It knows how to MATCH a request, not what a request or response CONTAINS. Concretely, fiber's Route struct (fiber/v3@v3.2.1 router.go:46) is only {Method, Name, Path, Params, Handlers} — there is no payload information in it to read.

Derivable (asserted here, all of it structural):

• method — the stack a route is registered in.
• path — the registered pattern, verbatim.
• path parameters — the pattern's own :name segments; a router that could not name them could not match them. Always required:true (a fiber path param is optional only if written :name?, which cloud does not use).
• product tag — the first /v1/ segment of that same pattern.

NOT derivable from the router (no amount of router-reading changes it — these come from the typed registry via Fold, and are absent on a route that has no typed op):

• request body schema. The router holds a func(*zip.Ctx) error. The request type is a LOCAL VARIABLE inside the handler body — clients/kms putSecret is the representative case: `var req secretPutRequest; json.Unmarshal( ctx.Body(), &req)`. The type exists in the package but never appears in the handler's signature, and Go has no reflection from a func value to the types it unmarshals internally. cloud.Handle[S] does not help: its type parameter S is the SERVICE (service.go:90), not the payload. cloud.Typed does not help either: it is an any→*zip.App mount adapter. What cannot be DERIVED can still be DECLARED: Register (register.go) is the seam a subsystem uses to state its binding structs once, next to its route table, and the schema is reflected from those structs.
• response body schema / status codes — same dead end, at the far end, with the same declaration seam (the success shape under a "2XX" range, because the exact code lives in the handler body).
• query and header parameters — read positionally via c.Query("k") at runtime; not part of the match, so the router has never heard of them.
• auth requirements — enforced by middleware and by guards wrapped around handlers (guard(s, cloud.Handle(s, listSecrets))), invisible as data.
• summaries/descriptions — prose that exists only in Go comments.
• wildcard semantics — a fiber `*` matches MULTIPLE segments greedily; OpenAPI's {param} matches one. The emitted {wildcardN} is the closest honest approximation and is NOT equivalent.
• whether a route is a real endpoint or a PROXY PREFIX. A catch-all like app.Post("/v1/billing/*") forwards to another service; the operations behind it (POST /v1/billing/deposit and friends) are not routes in this process and cannot appear. For products whose whole surface is one catch-all, this document can name the prefix and nothing under it.

The consequence for a consumer: this document is a complete and exact map of the API's SHAPE (every operation, its address, its product), and it describes PAYLOADS exactly as far as the typed registry does. A CLI can build its full command tree — `hanzo <product> <resource> <verb>` — and bind path params from it with no judgment calls, everywhere. It can typecheck a request body and pretty-print a response only for a typed op, and behind a catch-all it cannot enumerate subcommands at all.

The path to more schema is not a better reader. Two seams exist, both anchored in the handler's own Go types so neither can drift:

• Register (register.go): a subsystem declares its binding structs for a route it already serves — no handler change, schema by reflection. A registration renders ONLY when the router carries the route, so the document still cannot disagree with the router; schemas are additive metadata on routes that exist.
• zip's typed ops (zip.Get[In,Out]), which carry the In/Out types in the handler signature itself and also earn an MCP tool and a CLI command from the same registry entry (zip's third projection, zip/mcp.go). That is a per-handler refactor of business logic, and it composes with this: GetRoutes() already includes typed ops, so migration adds detail through the fold that is already running.

Chained handlers are not collisions ¶

Fiber MERGES byte-identical route patterns into ONE Route carrying both handlers chained, so a duplicate registration is invisible to an entry count and shows only as len(Handlers) > 1. That is true — but the converse does not hold, and this generator does NOT use that signal:

app.Post("/v1/billing/auto-recharge/run-all",
    commercemid.RequestContext(), commercemid.TokenRequired(),
    commercemid.PlatformOnly(), commercebilling.RunAutoRechargeAllOrgs)

is ONE registration with FOUR handlers — three middleware and a terminal handler (apps/commerce.go:151). The whole /v1/store/* surface is the same shape. 34 live routes carry chained handlers and every one is legitimate. A merged duplicate and a middleware chain are INDISTINGUISHABLE through the public API, so "handlers > 1" cannot mean "collision" fleet-wide; treating it as one would refuse a spec for a healthy router. (clients/bots/routes_test.go asserts exactly that rule, and is right to: it is a local truth for the bots/visor/runtime surface, where nothing chains middleware. It is not a global one.)

This costs the document nothing. Merged or chained, one pattern is one operation — which is what the spec emits either way. Detecting routing bugs is the bots guard's job, at the seam where the premise holds; the spec's only requirement is that (method, path) → operation stay injective, which From enforces via operationId uniqueness.

func FleetSpec(app *zip.App) (*Document, error)

func From(rs []Route, info Info, servers ...Server) (*Document, error)

func Spec(app *zip.App, info Info, servers ...Server) (*Document, error)

func Weave(parts []Part) (*Document, error)

type Info ¶

type Info struct {
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`
	Version     string `json:"version"`
}

Info is the OpenAPI info block.

type Media ¶ added in v1.801.299

type Media struct {
	Schema *Schema `json:"schema,omitempty"`
}

Media is an OpenAPI media type object: the schema of one content type.

type Operation ¶

type Operation struct {
	OperationID string      `json:"operationId"`
	Summary     string      `json:"summary,omitempty"`
	Description string      `json:"description,omitempty"`
	Tags        []string    `json:"tags,omitempty"`
	Parameters  []Parameter `json:"parameters,omitempty"`
	RequestBody any         `json:"requestBody,omitempty"`
	Responses   any         `json:"responses,omitempty"`
}

Operation is one operation.

Everything past Parameters is omitempty and comes from exactly two seams, both anchored in the handler's own Go types so neither can drift:

• Register (register.go): a subsystem declares its binding structs for a route it already serves — schema by reflection, attached only when the router carries the route.
• zip's typed ops, folded in from the registry (Fold): Summary/Description from the lifted godoc, query parameters and bodies from the In/Out types.

A route neither seam knows keeps exactly the structural facts the router can prove, and asserts no status code, content type or prose it has no evidence for — OpenAPI 3.1 makes `responses` OPTIONAL (3.0 required it), so absent stays valid and absent beats invented.

RequestBody and Responses are `any` because the two seams produce different (JSON-identical) shapes: Register builds the closed *RequestBody / map[string]*Response, the fold reuses zip's open maps verbatim.

type Parameter ¶

type Parameter struct {
	Name        string         `json:"name"`
	In          string         `json:"in"`
	Required    bool           `json:"required"`
	Description string         `json:"description,omitempty"`
	Schema      map[string]any `json:"schema,omitempty"`
}

Parameter is an OpenAPI parameter object.

From the ROUTER only path parameters are emitted: they are structural — the router matches on them — so they are derivable. From the REGISTRY a typed op's query parameters come too, with descriptions, because its input type says what they are. Schema is an open map because JSON Schema is an open vocabulary: the router asserts `{"type": "string"}` and nothing more, while a typed op's field can be any shape zip derives from its Go type.

type Part ¶ added in v1.801.299

type Part struct {
	App string
	Doc *Document
}

Part is one app's contribution: its document, and the name a conflict is reported against. The name is the app's, not the file's — a message naming two paths a human then has to map back to apps is a worse message.

type PathItem ¶

type PathItem map[string]*Operation

PathItem maps a lowercased HTTP method to its operation.

type Registry ¶ added in v1.801.299

type Registry struct {
	Ops     map[string]*Operation
	Schemas map[string]any
}

Registry is zip's typed-op projection, reduced to what the router cannot supply: the operations that carry schema and prose, keyed by the same "METHOD /templated/path" identity a Document is indexed by, and the schemas they $ref.

func Typed(app *zip.App) (Registry, error)

type RequestBody ¶ added in v1.801.299

type RequestBody struct {
	Content map[string]Media `json:"content"`
}

RequestBody is an OpenAPI request body object.

type Response ¶ added in v1.801.299

type Response struct {
	Description string           `json:"description"`
	Content     map[string]Media `json:"content,omitempty"`
}

Response is an OpenAPI response object. Description is required by the spec.

type Route ¶

type Route struct {
	Method string
	Path   string // fiber pattern, e.g. /v1/kms/orgs/:org/secrets/*
}

Route is one live route, reduced to what the router actually knows: where a request goes. Method and Path are the whole of it.

There is deliberately no handler count here. See Document's note on chained handlers for why that number cannot be interpreted.

func Live(app *zip.App) []Route

type Schema ¶

type Schema struct {
	Type                 string             `json:"type,omitempty"`
	Ref                  string             `json:"$ref,omitempty"`
	Items                *Schema            `json:"items,omitempty"`
	Properties           map[string]*Schema `json:"properties,omitempty"`
	AdditionalProperties *Schema            `json:"additionalProperties,omitempty"`
}

Schema is the sliver of JSON Schema this generator can honestly assert as a CLOSED struct: primitive types for path parameters, and — for routes whose subsystem declared its bodies via Register — objects, arrays, and $refs derived by reflection from the handler's own binding structs. Typed-op schemas do NOT pass through it: zip already derives arbitrary JSON Schema from the In/Out Go types, and restating that open vocabulary here would be a second, lossier copy — they travel as `any` (see Fold).

type Server ¶

type Server struct {
	URL string `json:"url"`
}

Server is an OpenAPI server entry.

type Tag ¶

type Tag struct {
	Name string `json:"name"`
}

Tag is an OpenAPI tag — one per product, so a consumer can read the product list off the document without walking every path.