openapi

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2026 License: GPL-3.0 Imports: 6 Imported by: 1

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

View Source
const (
	InPath   = "path"
	InQuery  = "query"
	InHeader = "header"
)

Parameter locations.

View Source
const (
	TypeString  = "string"
	TypeInteger = "integer"
	TypeNumber  = "number"
	TypeBoolean = "boolean"
	TypeArray   = "array"
	TypeObject  = "object"
)

JSON schema type names.

View Source
const SchemaRefPrefix = "#/components/schemas/"

SchemaRefPrefix is how a `$ref` names a component schema.

Variables

This section is empty.

Functions

func SortedKeys

func SortedKeys[V any](m map[string]V) []string

SortedKeys returns the keys of a map in sorted order, for deterministic output.

Types

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"`
}

MediaType is the schema of one media type of a body or response.

type Method

type Method struct {
	Method    string // GET, POST, ...
	Operation *Operation
}

Method is one operation of a path together with its HTTP method.

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:"-"`
}

Operation is one HTTP method on one path.

func (*Operation) Parameter

func (o *Operation) Parameter(in, name string) *Parameter

Parameter returns the operation's parameter of that location and name (case-insensitive, as both servers bind them), or nil.

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:"-"`
}

Parameter is a path, query or header parameter.

func (*Parameter) DeepObject

func (p *Parameter) DeepObject() bool

DeepObject reports whether an object parameter is sent as one key per field, name[field]=value, rather than as one JSON string.

func (*Parameter) Exploded

func (p *Parameter) Exploded() bool

Exploded reports whether an array parameter is sent as one key per value rather than comma-separated: OpenAPI's default for a query parameter (style form, explode true), but not for a header (style simple, explode false).

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.

func (*PathItem) Methods

func (p *PathItem) Methods() []Method

Methods returns the imported operations of a path in a fixed method order.

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"`
	Type        string             `json:"type"`
	Format      string             `json:"format"`
	Description string             `json:"description"`
	Nullable    bool               `json:"nullable"`
	Enum        []json.RawMessage  `json:"enum"`
	Properties  map[string]*Schema `json:"properties"`
	// Required names the properties an object must carry.
	Required             []string        `json:"required"`
	Items                *Schema         `json:"items"`
	AdditionalProperties json.RawMessage `json:"additionalProperties"`
	AllOf                []*Schema       `json:"allOf"`
	OneOf                []*Schema       `json:"oneOf"`
	AnyOf                []*Schema       `json:"anyOf"`
}

Schema is a JSON schema object, as far as the two specs use it.

func (*Schema) Additional

func (s *Schema) Additional() (sch *Schema, ok bool)

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

func (s *Schema) EnumValues() []string

EnumValues returns the enum members as strings. Both specs only use string enums; anything else is rendered through its JSON form.

func (*Schema) IsEnum

func (s *Schema) IsEnum() bool

IsEnum reports whether a schema defines a string enum type.

func (*Schema) IsUnion

func (s *Schema) IsUnion() bool

IsUnion reports whether a schema is a oneOf/anyOf union, which cannot be represented as a struct.

func (*Schema) RefName

func (s *Schema) RefName() string

RefName returns the schema name a `$ref` points at, or "" when the schema is not a reference. A single-element allOf wrapping a $ref (how Jellyfin attaches descriptions and nullable to references) counts as a reference.

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 Load

func Load(path string) (*Spec, error)

Load reads and decodes an OpenAPI 3 JSON document.

func Parse

func Parse(raw []byte) (*Spec, error)

Parse decodes an OpenAPI 3 JSON document.

func (*Spec) Operation

func (s *Spec) Operation(method, path string) *Operation

Operation returns the operation for an HTTP method on a path, or nil.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL