Documentation
¶
Overview ¶
Command zipdoc makes a doc comment the spec.
It walks a package for typed registrations — zip.Get[In,Out](app, path, fn) and its Post/Put/Patch/Delete siblings — takes the doc comment on each handler and on each field of its In and Out types, and writes a file that hands them to zip.Describe at init. From there they are the operation's description, its fields' descriptions and its request/response examples in the OpenAPI spec zip serves, and in the MCP tools it exposes.
The point is that nothing is written twice. A summary passed to WithSummary sitting under a doc comment that says the same thing is two places to change and one to forget; this pass removes the second place.
Put this above the package's route registrations:
//go:generate zipdoc
and write handlers the way Go already asks you to:
// ListInvoices returns every invoice for the caller's org, newest first.
//
// Example: {"org": "hanzo", "limit": 25}
// Response: {"invoices": [{"id": "inv_1", "cents": 1200}]}
func ListInvoices(ctx context.Context, in *ListIn) (*ListOut, error)
A malformed Example or Response fails generation rather than shipping a spec that is wrong.
Usage:
zipdoc [-o name] [-check] [packages]
With -check nothing is written and a file that no longer matches its source is an error. That is the CI gate: the spec is derived from the code, so it cannot drift from it.
Source Files