Documentation
¶
Overview ¶
Package openapi publishes the OpenAPI document that specifies the HTTP API.
The document is authoritative for the API: the Go server in internal/api and the TypeScript types in web/ts/api/types.ts are both generated from it. It lives at the repository root, because a generator's input is not a detail of any one package, and is embedded by main — the only package that can embed a file there — and handed to serve, which publishes it at /openapi.json and /openapi.yaml.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Document ¶
type Document struct {
// contains filtered or unexported fields
}
Document is the OpenAPI document as written, with the JSON form derived from it. Keeping one source and converting is what stops the two representations from drifting.
func (*Document) JSONHandler ¶
JSONHandler serves /openapi.json.
func (*Document) Operations ¶
Operations reads the operations out of the document, keyed by operation ID — the identifier the generated server reports for the request it is serving.
func (*Document) YAMLHandler ¶
YAMLHandler serves /openapi.yaml.
type Operation ¶
type Operation struct {
// QueryParameters are the query parameters the operation declares. Any
// other one is refused rather than ignored, exactly as an unrecognised body
// field is: a parameter the server never reads is a thing the client
// believes it said.
QueryParameters map[string]bool
// TakesBody says whether the operation declares a request body. One that
// does not refuses a body rather than ignoring it, for the same reason.
TakesBody bool
// BodyMediaTypes are the content types the operation's request body
// declares, which is what a body carried to it must claim to be. Every
// operation but the attachment upload declares application/json; that one
// declares application/octet-stream, and its body is bytes rather than
// text.
BodyMediaTypes []string
}
Operation is what the document says one operation accepts.
It is read out of the document rather than restated in Go, because both rules below are rules about what the document declares: a table of names beside the generated code would be a second copy of it, free to drift.
func (Operation) AcceptsBodyType ¶
AcceptsBodyType reports whether a body claiming this Content-Type is one the operation declares.
It takes the header value as it arrived and reduces it itself: a media type is case-insensitive, and what follows the first ";" is parameters rather than the type — "application/json; charset=utf-8" is a JSON body. Doing that here rather than at the call site is what stops a second caller from comparing a raw header against a bare type and refusing every request that spells out its charset.
func (Operation) DeclaresJSONBody ¶
DeclaresJSONBody reports whether the operation's body is JSON, which is what decides whether the text rules apply to its bytes.
Source Files