Documentation
¶
Overview ¶
Package openapigen generates an OpenAPI 3.1 document from the compiled document, so a specification cannot describe an API that does not exist.
It exists for the reason the server and client generators do, and the IR was shaped around it before it was written: ir.Endpoint.Pattern is computed once at freeze "so the router, the OpenAPI document, and the TypeScript client cannot disagree about path shape", ir.Endpoint.Errors stores bare status codes because every one of them shares the Error body, and ir.Field.Description is the single copy of the prose precisely so one sentence reaches a Go doc comment and an OpenAPI description alike. A hand-written specification is a second description of the API, and it goes wrong quietly — nothing fails to compile when a document keeps describing a field that was renamed a year ago.
The document is assembled as a model and rendered, rather than written as text. A specification built by concatenating strings is one that eventually stops parsing, and the failure lands on whoever downloaded it.
What it does not describe is what the compiled document does not carry. The routes the authentication module and the notification inbox mount are hand-written and reach no IR endpoint, so they are absent here and said to be absent in info.description — an omission a reader can see beats one they discover.
The two routes the document is itself served on are the exception that proves the rule: a project that turns `api.openapi.serve` on gets them described here as well, because they are routes the same mux answers. See spec.go.
Index ¶
Constants ¶
const SpecVersion = "3.1"
SpecVersion is the OpenAPI version emitted, and the only one accepted.
3.1 has no way to express an operation on the QUERY method, so a search is documented as the POST alias the compiler already emits beside it. 3.2 can express it and almost nothing can read 3.2 yet; when that changes, this becomes a branch rather than a constant, which is why the option exists and is validated instead of ignored.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Generator ¶
type Generator struct{}
Generator emits the OpenAPI document.
func (*Generator) Description ¶
Description implements gen.Generator.
type Options ¶
type Options struct {
// Version selects the specification version. Only "3.1" is accepted.
Version string `json:"version"`
// Formats are the renderings to write: json, yaml, or both.
Formats []string `json:"formats"`
// Servers are the origins the API answers on.
//
// Deprecated: rig.yaml's top-level `servers:` block names the deployments
// for every SDK generator as well as for this one, so the document and the
// clients cannot disagree about where the API is. This is read only when
// that block is absent, and rig warns (RIG3010) when it is set.
Servers []Server `json:"servers"`
// Electric says whether the live-sync shape routes are described. They are
// routes of this API and are documented by default; a project that would
// rather not publish a proxied protocol turns them off here.
Electric *bool `json:"electric"`
}
Options configure the generator.
type Server
deprecated
Server is one origin the API answers on.
Deprecated: see Options.Servers.
Source Files