Documentation
¶
Overview ¶
Package openapi generates an OpenAPI 3.1 document from momo models. The document describes CRUD and list endpoints with allowlisted filters and keyset pagination.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Document ¶
Document returns the OpenAPI 3.1 document for the models of g as indented JSON, and the diagnostics for columns with no mapping and for options that cannot produce a valid document. Sensitive columns are not part of the API, and relations are not properties.
func Handlers ¶ added in v0.6.0
Handlers returns the Go source of net/http handlers for the models of g, in package pkg, and the diagnostics for what it left out. Each model with a single int64 primary key gets a type MHandler with a DB field and a Routes method that registers the routes of its enabled operations (Options.Ops) on a *http.ServeMux; a model that cannot be served is skipped with a diagnostic, and the rest is still generated. The source is nil only when the package name or base path is invalid.
The handlers use only the typed builders, filter through the generated ColumnByName allowlist, page with keyset cursors on the primary key, accept application/json bodies of at most 1 MiB, and answer errors as {"error": "..."} with fixed messages: a unique or foreign key violation is 409, a check or not-null violation 400, a busy database or a serialization failure 503, a request whose context was cancelled 499 and one whose deadline passed 504. With Options.OnError every such error is first passed to that function with the operation name and the original error. PUT needs every required property; a property that is absent and not required keeps its stored value. They do no authentication or authorization: wrap the mux. The response keys are exactly the column properties of the model's schema. The output is deterministic.
Types ¶
type Options ¶
type Options struct {
Title, Version string
// BasePath prefixes every path, for example /v1. It is empty or starts
// with a slash.
BasePath string
// Handlers asks the plugin to also emit net/http handlers; Document does
// not read it.
Handlers bool
// Ops chooses the operations served per model; nil serves every one. The
// document and the handlers both read it.
Ops apiquery.Ops
// OnError names a function in the handlers package with the signature
// func(ctx context.Context, op string, err error). Every handler calls it
// once for each error it answers from a statement, with the operation name
// (the operationId of the document, for example getDocument) and the
// original error, before it writes the fixed message. Empty means no hook.
// Document does not read it.
OnError string
}
Options configures Document.
type Plugin ¶ added in v0.6.0
type Plugin struct {
// Dir is the output directory.
Dir string
// Package is the Go package name of the handlers; it defaults to the base
// name of Dir.
Package string
// Options is passed to Document and Handlers.
Options Options
}
Plugin is the gen.Plugin that writes the OpenAPI document and, when Options.Handlers is set, the net/http handlers.
func (Plugin) APIVersion ¶ added in v0.6.0
APIVersion returns gen.PluginAPIVersion.
func (Plugin) Generate ¶ added in v0.6.0
Generate writes <Dir>/openapi.yaml through w.Text, and, only when Options.Handlers is true, <Dir>/handlers_gen.go through w.File. The document is written as YAML, which OpenAPI accepts as a JSON equivalent, because a JSON file has no place for the generated-file header the writer requires.
A model that cannot be served is left out and named in a comment at the top of each output; it does not fail the run. An invalid option does, and so does a handlers_gen.go left behind by an earlier run with handlers: true, which would otherwise keep serving routes the document no longer lists.
Source Files