Documentation
¶
Overview ¶
Package openapi decodes the subset of an OpenAPI 3 document the importer reads. Anything not listed here (servers, security, examples, xml hints) is ignored. The types are mutable on purpose: workarounds patch a loaded document before it is normalised into definitions.
Index ¶
- Constants
- func Camel(s string) string
- func JSONMedia(mediaType string) bool
- func PathJoin(path, name string) string
- func PathName(path string) string
- func PickJSON(content map[string]*MediaType) (string, bool)
- func SortedKeys[V any](m map[string]V) []string
- type CommandSet
- type Example
- type MediaType
- type Method
- type Operation
- type Parameter
- type PathItem
- type Place
- type RequestBody
- type Response
- type Schema
- type Spec
Constants ¶
const ( InPath = "path" InQuery = "query" InHeader = "header" )
Parameter locations.
const ( FormatUnixSeconds = "unix-seconds" FormatUnixMillis = "unix-milliseconds" )
FormatUnixSeconds and FormatUnixMillis are the formats a workaround gives an integer that is a date (seconds or milliseconds since 1970), which no document declares.
const ( TypeString = "string" TypeInteger = "integer" TypeNumber = "number" TypeBoolean = "boolean" TypeArray = "array" TypeObject = "object" )
JSON schema type names.
const SchemaRefPrefix = "#/components/schemas/"
SchemaRefPrefix is how a `$ref` names a component schema.
Variables ¶
This section is empty.
Functions ¶
func Camel ¶ added in v0.7.0
Camel joins the alphanumeric pieces of s, upper-casing the first letter of each piece and keeping the rest as spelled: "QueryResult_BaseItemDto" → "QueryResultBaseItemDto", "master.m3u8" → "MasterM3u8", "user_usage_stats" → "UserUsageStats", "GetFirstUser_2" → "GetFirstUser2". A leading digit gets an "N" prefix so the result is always a valid identifier.
func JSONMedia ¶ added in v0.6.0
JSONMedia reports whether a media type is JSON: application/json, text/json or one that ends +json, whatever its parameters.
func PickJSON ¶ added in v0.6.0
PickJSON returns the JSON media type of a body or response's content: plain application/json when listed, else the first JSON type.
func SortedKeys ¶
SortedKeys returns the keys of a map in sorted order, for deterministic output.
Types ¶
type CommandSet ¶ added in v0.8.0
type CommandSet struct {
Get string
Status string
Finished []string
Failed []string
Commands map[string]string
}
CommandSet is how a server that queues commands by name through one operation is followed: Get is the operation that answers a queued command by its id ("GET /api/v3/command/{id}"), Status the field of its answer that says how far it is, Finished the values that mean it is over and Failed those among them that mean it failed, and Commands the schema each command's body is, by the command's name as the server takes it.
type Example ¶
type Example struct {
Value json.RawMessage `json:"value"`
}
Example is one named example of a media type's content. TMDB's document keeps the only true shape of its request bodies here.
type MediaType ¶
type MediaType struct {
Schema *Schema `json:"schema"`
Examples map[string]*Example `json:"examples"`
// Text is set by a workaround for an answer that is short text and not
// JSON, to be read whole into a string where an answer of another type
// than JSON is otherwise a file left for its caller to read. No document
// carries it: a log file is text too, and is not to be held in memory.
Text bool `json:"-"`
}
MediaType is the schema of one media type of a body or response.
type Operation ¶
type Operation struct {
OperationID string `json:"operationId"`
Tags []string `json:"tags"`
Summary string `json:"summary"`
Description string `json:"description"`
Deprecated bool `json:"deprecated"`
Parameters []*Parameter `json:"parameters"`
RequestBody *RequestBody `json:"requestBody"`
Responses map[string]*Response `json:"responses"`
// Name is the Go method a workaround gives the operation, in place of
// the one its path or its operationId would make: how two operations
// that make the same name are told apart. No document carries it.
Name string `json:"-"`
// Commands is set by a workaround on an operation that queues a command named in its body, and says which commands there
// are and how a queued one is followed. No document carries it.
Commands *CommandSet `json:"-"`
}
Operation is one HTTP method on one path.
type Parameter ¶
type Parameter struct {
Name string `json:"name"`
In string `json:"in"`
Description string `json:"description"`
Required bool `json:"required"`
Deprecated bool `json:"deprecated"`
Style string `json:"style"`
Explode *bool `json:"explode"`
Schema *Schema `json:"schema"`
// Added is set for a parameter a workaround added, which no document
// can say of its own: the importer keeps an added header named Accept,
// where it ignores a document's as OpenAPI says to.
Added bool `json:"-"`
// Field is the Go field a workaround chose for the parameter, when the
// name's own would clash with another parameter of the same name
// (a list added beside the string it joins); "" is the name's own.
Field string `json:"-"`
}
Parameter is a path, query or header parameter.
func (*Parameter) DeepObject ¶
DeepObject reports whether an object parameter is sent as one key per field, name[field]=value, rather than as one JSON string.
type PathItem ¶
type PathItem struct {
Get *Operation `json:"get"`
Post *Operation `json:"post"`
Put *Operation `json:"put"`
Delete *Operation `json:"delete"`
Patch *Operation `json:"patch"`
}
PathItem holds the operations of one path. HEAD and OPTIONS are not imported: the servers use them only for cache probes and CORS.
type Place ¶ added in v0.7.0
Place is one place in a document as a workaround's In or Except names it: an operation ("GET /api/stacks") or a component schema ("Container"), and an optional path inside it, ".status" for the property at the top alone, "containerDetails.status" for the one at that path.
type RequestBody ¶
type RequestBody struct {
Required bool `json:"required"`
Content map[string]*MediaType `json:"content"`
}
RequestBody maps media types to their schema.
type Response ¶
type Response struct {
Description string `json:"description"`
Content map[string]*MediaType `json:"content"`
}
Response is one status code of an operation. A response that is a `$ref` into components/responses (Emby's error codes) carries no content, and decodes to one with none.
type Schema ¶
type Schema struct {
Ref string `json:"$ref,omitempty"`
Type string `json:"type,omitempty"`
Format string `json:"format,omitempty"`
Description string `json:"description,omitempty"`
Nullable bool `json:"nullable,omitempty"`
Enum []json.RawMessage `json:"enum,omitempty"`
Properties map[string]*Schema `json:"properties,omitempty"`
// Required names the properties an object must carry.
Required []string `json:"required,omitempty"`
Items *Schema `json:"items,omitempty"`
AdditionalProperties json.RawMessage `json:"additionalProperties,omitempty"`
AllOf []*Schema `json:"allOf,omitempty"`
OneOf []*Schema `json:"oneOf,omitempty"`
AnyOf []*Schema `json:"anyOf,omitempty"`
}
Schema is a JSON schema object, as far as the two specs use it.
func (*Schema) Additional ¶
Additional returns the additionalProperties schema. ok is false when the schema does not allow additional properties; a bare `true` or `{}` yields an empty schema.
func (*Schema) EnumValues ¶
EnumValues returns the enum members as strings. Both specs only use string enums; anything else is rendered through its JSON form.
type Spec ¶
type Spec struct {
OpenAPI string `json:"openapi"`
Info struct {
Title string `json:"title"`
Version string `json:"version"`
} `json:"info"`
Paths map[string]*PathItem `json:"paths"`
Components struct {
Schemas map[string]*Schema `json:"schemas"`
} `json:"components"`
}
Spec is an OpenAPI 3 document.
func (*Spec) EachSchema ¶ added in v0.7.0
EachSchema calls fn for every schema in the document: where is the operation it belongs to, as "GET /path", or the component schema's name, and path where it sits, the property names down to it joined by dots ("containerDetails.status"), a parameter's name, or "" for one that is not named. A list adds nothing to the path: its items sit where it does. It covers the component schemas, each operation's parameters, request body and answers, and everything nested in them.