Documentation
¶
Overview ¶
Package openapi writes Pando's HTTP API as an OpenAPI 3.1 document, read from the handlers that serve it.
R-261 makes the API the product, and a description of it written by hand is a second opinion about it that drifts the first time a field is added. So nothing here is written by hand except what the code cannot say (see overrides.go). The routes are the router's: (*httpapi.Server).Routes is read as source, so a route is described because it is registered. Each route's request body is the type its handler decodes into; each response is what its handler passes to JSON, with the status it passes — a map literal's keys are read from the literal, and a struct is described field by field the way encoding/json writes it, as cmd/gen-api-types describes it for the console. The summaries, groups and verbs are httpapi's routeDocs, the table TestR261_EveryRouteIsDocumented holds to the router.
It reads source, so it runs where the source is: `make reference` writes docs/openapi.json with it, and the binary does not carry it.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Components ¶
type Components struct {
Schemas map[string]*Schema `json:"schemas"`
Responses map[string]*Response `json:"responses"`
SecuritySchemes map[string]SecurityScheme `json:"securitySchemes"`
}
Components are the document's shared parts.
type Document ¶
type Document struct {
OpenAPI string `json:"openapi"`
Info Info `json:"info"`
Servers []Server `json:"servers"`
Security []map[string][]string `json:"security"`
Tags []Tag `json:"tags"`
Paths map[string]map[string]*Operation `json:"paths"`
Components Components `json:"components"`
}
Document is an OpenAPI 3.1 document.
type Header ¶
type Header struct {
Description string `json:"description,omitempty"`
Schema *Schema `json:"schema"`
}
Header is a response header.
type Info ¶
type Info struct {
Title string `json:"title"`
Version string `json:"version"`
Description string `json:"description"`
}
Info is the document's title and version.
type MediaType ¶
type MediaType struct {
Schema *Schema `json:"schema"`
}
MediaType is a body in one content type.
type Operation ¶
type Operation struct {
OperationID string `json:"operationId"`
Summary string `json:"summary"`
Description string `json:"description,omitempty"`
Tags []string `json:"tags"`
Parameters []Parameter `json:"parameters,omitempty"`
RequestBody *RequestBody `json:"requestBody,omitempty"`
Responses map[string]*Response `json:"responses"`
Security *[]map[string][]string `json:"security,omitempty"`
Verb string `json:"x-pando-verb,omitempty"`
}
Operation is one method on one path.
type Parameter ¶
type Parameter struct {
Name string `json:"name"`
In string `json:"in"`
Required bool `json:"required,omitempty"`
Description string `json:"description,omitempty"`
Schema *Schema `json:"schema"`
}
Parameter is a path, query or header parameter.
type Props ¶
type Props []Prop
Props marshals as a JSON object in the order the fields are declared, which is the order the Go struct writes them and the order a person reads them in.
func (Props) MarshalJSON ¶
MarshalJSON writes the properties as an object, in order.
type RequestBody ¶
type RequestBody struct {
Description string `json:"description,omitempty"`
Required bool `json:"required,omitempty"`
Content map[string]MediaType `json:"content"`
}
RequestBody is what an operation reads.
type Response ¶
type Response struct {
Ref string `json:"$ref,omitempty"`
Description string `json:"description,omitempty"`
Headers map[string]Header `json:"headers,omitempty"`
Content map[string]MediaType `json:"content,omitempty"`
}
Response is one answer.
type Schema ¶
type Schema struct {
// Ref is a component's internal key while the document is assembled, and
// "#/components/schemas/<name>" once names are settled.
Ref string `json:"$ref,omitempty"`
Type any `json:"type,omitempty"`
Format string `json:"format,omitempty"`
ContentEncoding string `json:"contentEncoding,omitempty"`
Description string `json:"description,omitempty"`
Enum []string `json:"enum,omitempty"`
Items *Schema `json:"items,omitempty"`
Properties Props `json:"properties,omitempty"`
Required []string `json:"required,omitempty"`
AdditionalProperties *Schema `json:"additionalProperties,omitempty"`
AnyOf []*Schema `json:"anyOf,omitempty"`
OneOf []*Schema `json:"oneOf,omitempty"`
// contains filtered or unexported fields
}
Schema is a JSON Schema as OpenAPI 3.1 has it: the subset this generator writes, in the order a reader expects the keys.
type SecurityScheme ¶
type SecurityScheme struct {
Type string `json:"type"`
Scheme string `json:"scheme,omitempty"`
In string `json:"in,omitempty"`
Name string `json:"name,omitempty"`
Description string `json:"description,omitempty"`
}
SecurityScheme is one way to authenticate.
type Server ¶
type Server struct {
URL string `json:"url"`
Description string `json:"description"`
Variables map[string]ServerVariable `json:"variables"`
}
Server is where the API is reached.
type ServerVariable ¶
type ServerVariable struct {
Default string `json:"default"`
Description string `json:"description"`
}
ServerVariable is a part of a server's URL the reader fills in.
Source Files