oas

Documentation

Overview

Package oas provides a representation of the OpenAPI Specification (OAS) Version 3.1.0

Index

• Variables
• type Callback
• type Components
• type ContactDetails
• type ContentType
• type Discriminator
• type Document
  • func (doc *Document) Lookup(namespace, name string) *Schema
  • func (doc *Document) Register(namespace, name string, schema *Schema)
• type Email
• type Encoding
• type Example
• type Expression
• type ExternalDocumentation
• type Format
• type Header
• type Information
• type LicenseID
• type Licensing
• type Link
• type Markdown
• type MediaType
• type Name
• type OauthFlow
• type OauthFlows
• type Operation
• type OperationID
• type Parameter
• type ParameterLocation
• type ParameterStyle
• type PathItem
• type Property
• type PropertyName
• type Readable
• type Reference
• type Registry
• type RequestBody
• type Response
• type ResponseKey
• type Schema
  • func (schema *Schema) Lookup(namespace, name string) *Schema
  • func (schema *Schema) Register(namespace, name string, value *Schema)
• type SecurityScheme
• type SecuritySchemeID
• type SecuritySchemeType
• type Server
• type ServerVariable
• type Tag
• type Type
• type TypeSet
  • func (t TypeSet) MarshalJSON() ([]byte, error)
  • func (t *TypeSet) UnmarshalJSON(data []byte) error
• type URI
• type URL
• type Version
• type XML

Variables

var Formats = xyz.AccessorFor(Format.Values)

var ParameterLocations = xyz.AccessorFor(ParameterLocation.Values)

var ParameterStyles = xyz.AccessorFor(ParameterStyle.Values)

var ResponseKeys = xyz.AccessorFor(ResponseKey.Values)

var SecuritySchemeTypes = xyz.AccessorFor(SecuritySchemeType.Values)

var Types = xyz.AccessorFor(Type.Values)

Types

type Callback

type Callback map[string]*PathItem

type Components

type Components struct {
	Schemas         map[string]*Schema                   `json:"schemas,omitempty"`
	Responses       map[string]*Response                 `json:"responses,omitempty"`
	Parameters      map[string]*Parameter                `json:"parameters,omitempty"`
	Examples        map[string]*Example                  `json:"examples,omitempty"`
	RequestBodies   map[string]*RequestBody              `json:"requestBodies,omitempty"`
	Headers         map[string]*Header                   `json:"headers,omitempty"`
	SecuritySchemes map[SecuritySchemeID]*SecurityScheme `json:"securitySchemes,omitempty"`
	Links           map[string]*Link                     `json:"links,omitempty"`
	Callbacks       map[string]*Callback                 `json:"callbacks,omitempty"`
	PathItems       map[string]*PathItem                 `json:"pathItems,omitempty"`
}

type ContactDetails

type ContactDetails struct {
	Name  Name  `json:"name,omitempty"`
	URL   URL   `json:"url,omitempty"`
	Email Email `json:"email,omitempty"`
}

ContactDetails for an API.

type ContentType

type ContentType string

type Discriminator

type Discriminator struct {
	PropertyName string            `json:"propertyName"`
	Mapping      map[string]string `json:"mapping,omitempty"`
}

type Document

type Document struct {
	OpenAPI               Version                       `json:"openapi"`
	Information           Information                   `json:"info"`
	SchemaDialect         URI                           `json:"jsonSchemaDialect,omitempty"`
	Servers               []Server                      `json:"servers,omitempty"`
	Paths                 map[string]PathItem           `json:"paths,omitempty"`
	Webhooks              map[string]*PathItem          `json:"webhooks,omitempty"`
	Components            *Components                   `json:"components,omitempty"`
	Security              []map[string]SecuritySchemeID `json:"security,omitempty"`
	Tags                  []Tag                         `json:"tags,omitempty"`
	ExternalDocumentation *ExternalDocumentation        `json:"externalDocs,omitempty"`
}

func (*Document) Lookup

func (doc *Document) Lookup(namespace, name string) *Schema

func (*Document) Register

func (doc *Document) Register(namespace, name string, schema *Schema)

type Email

type Email string

type Encoding

type Encoding struct {
	ContentType   ContentType        `json:"contentType,omitempty"`
	Headers       map[string]*Header `json:"headers,omitempty"`
	Style         ParameterStyle     `json:"style,omitempty"`
	Explode       bool               `json:"explode,omitempty"`
	AllowReserved bool               `json:"allowReserved,omitempty"`
}

type Example

type Example struct {
	Summary       Readable        `json:"summary,omitempty"`
	Description   Readable        `json:"description,omitempty"`
	Value         json.RawMessage `json:"value,omitempty"`
	ExternalValue URI             `json:"externalValue,omitempty"`
}

type Expression

type Expression string

type ExternalDocumentation

type ExternalDocumentation struct {
	Description Readable `json:"description,omitempty"`
	URL         URL      `json:"url"`
}

type Format

type Format xyz.Switch[string, struct {
	DateTime Format `json:"date-time"`
	Time     Format `json:"time"`
	Date     Format `json:"date"`
	Duration Format `json:"duration"`
	Email    Format `json:"email"`
	Hostname Format `json:"hostname"`
	IPv4     Format `json:"ipv4"`
	IPv6     Format `json:"ipv6"`
	UUID     Format `json:"uuid"`
	URI      Format `json:"uri"`
	Regex    Format `json:"regex"`

	Int32    Format `json:"int32"`
	Int64    Format `json:"int64"`
	Float    Format `json:"float"`
	Double   Format `json:"double"`
	Password Format `json:"password"`
}]

type Header

type Header struct {
	Description     Readable             `json:"description,omitempty"`
	Required        bool                 `json:"required,omitempty"`
	Deprecated      bool                 `json:"deprecated,omitempty"`
	AllowEmptyValue bool                 `json:"allowEmptyValue,omitempty"`
	Style           ParameterStyle       `json:"style,omitempty"`
	Explode         bool                 `json:"explode,omitempty"`
	AllowReserved   bool                 `json:"allowReserved,omitempty"`
	Schema          *Schema              `json:"schema,omitempty"`
	Example         json.RawMessage      `json:"example,omitempty"`
	Examples        map[string]*Example  `json:"examples,omitempty"`
	Content         map[string]MediaType `json:"content,omitempty"`
}

type Information

type Information struct {
	Title           Readable        `json:"title"`
	Summary         Readable        `json:"summary,omitempty"`
	Version         Version         `json:"version"`
	License         *Licensing      `json:"license,omitempty"`
	TermsConditions URL             `json:"termsOfService,omitempty"`
	Description     Markdown        `json:"description,omitempty"`
	Contact         *ContactDetails `json:"contact,omitempty"`
}

Information about an API.

type LicenseID

type LicenseID string

type Licensing

type Licensing struct {
	ID   LicenseID `json:"identifier,omitempty"`
	Name Readable  `json:"name"`
	URL  URL       `json:"url,omitempty"`
}

Licensing information for the implementation of the API.

type Link

type Link struct {
	OperationRef *Operation     `json:"operationRef,omitempty"`
	OperationID  OperationID    `json:"operationId,omitempty"`
	Parameters   map[string]any `json:"parameters,omitempty"`
	RequestBody  any            `json:"requestBody,omitempty"`
	Description  Readable       `json:"description,omitempty"`
	Server       *Server        `json:"server,omitempty"`
}

type Markdown

type Markdown string

type MediaType

type MediaType struct {
	Schema   *Schema             `json:"schema,omitempty"`
	Example  json.RawMessage     `json:"example,omitempty"`
	Examples map[string]*Example `json:"examples,omitempty"`
	Encoding map[string]Encoding `json:"encoding,omitempty"`
}

type Name

type Name string

type OauthFlow

type OauthFlow struct {
	Authorization URL            `json:"authorizationUrl,omitempty"`
	Token         URL            `json:"tokenUrl,omitempty"`
	Refresh       URL            `json:"refreshUrl,omitempty"`
	Scopes        map[string]any `json:"scopes,omitempty"`
}

type OauthFlows

type OauthFlows struct {
	Implicit          *OauthFlow `json:"implicit,omitempty"`
	Password          *OauthFlow `json:"password,omitempty"`
	ClientCredentials *OauthFlow `json:"clientCredentials,omitempty"`
	AuthorizationCode *OauthFlow `json:"authorizationCode,omitempty"`
}

type Operation

type Operation struct {
	ID          OperationID                   `json:"operationId,omitempty"`
	Tags        []string                      `json:"tags,omitempty"`
	Summary     Readable                      `json:"summary,omitempty"`
	Description Readable                      `json:"description,omitempty"`
	SeeAlso     *ExternalDocumentation        `json:"externalDocs,omitempty"`
	Parameters  []*Parameter                  `json:"parameters,omitempty"`
	RequestBody *RequestBody                  `json:"requestBody,omitempty"`
	Responses   map[ResponseKey]*Response     `json:"responses,omitempty"`
	Callbacks   map[string]*Callback          `json:"callbacks,omitempty"`
	Deprecated  bool                          `json:"deprecated,omitempty"`
	Security    []map[string]SecuritySchemeID `json:"security,omitempty"`
	Servers     []Server                      `json:"servers,omitempty"`
}

type OperationID

type OperationID string

type Parameter

type Parameter struct {
	Name            Readable             `json:"name"`
	In              ParameterLocation    `json:"in"`
	Description     Readable             `json:"description,omitempty"`
	Required        bool                 `json:"required,omitempty"`
	Deprecated      bool                 `json:"deprecated,omitempty"`
	AllowEmptyValue bool                 `json:"allowEmptyValue,omitempty"`
	Style           ParameterStyle       `json:"style,omitempty"`
	Explode         bool                 `json:"explode,omitempty"`
	AllowReserved   bool                 `json:"allowReserved,omitempty"`
	Schema          *Schema              `json:"schema,omitempty"`
	Example         json.RawMessage      `json:"example,omitempty"`
	Examples        map[string]*Example  `json:"examples,omitempty"`
	Content         map[string]MediaType `json:"content,omitempty"`
}

type ParameterLocation

type ParameterLocation xyz.Switch[string, struct {
	Query  ParameterLocation `json:"query"`
	Header ParameterLocation `json:"header"`
	Path   ParameterLocation `json:"path"`
	Cookie ParameterLocation `json:"cookie"`
}]

type ParameterStyle

type ParameterStyle xyz.Switch[string, struct {
	Matrix         ParameterStyle `json:"matrix"`
	Label          ParameterStyle `json:"label"`
	Form           ParameterStyle `json:"form"`
	Simple         ParameterStyle `json:"simple"`
	SpaceDelimited ParameterStyle `json:"spaceDelimited"`
	PipeDelimited  ParameterStyle `json:"pipeDelimited"`
	DeepObject     ParameterStyle `json:"deepObject"`
}]

type PathItem

type PathItem struct {
	Extends    *PathItem    `json:"$ref,omitempty"`
	Summary    Readable     `json:"summary,omitempty"`
	Desciption Readable     `json:"description,omitempty"`
	Get        *Operation   `json:"get,omitempty"`
	Put        *Operation   `json:"put,omitempty"`
	Post       *Operation   `json:"post,omitempty"`
	Delete     *Operation   `json:"delete,omitempty"`
	Options    *Operation   `json:"options,omitempty"`
	Head       *Operation   `json:"head,omitempty"`
	Patch      *Operation   `json:"patch,omitempty"`
	Trace      *Operation   `json:"trace,omitempty"`
	Servers    []Server     `json:"servers,omitempty"`
	Parameters []*Parameter `json:"parameters,omitempty"`
}

type Property

type Property struct {
	Type        Type     `json:"type,omitempty"`
	Description Readable `json:"description,omitempty"`
}

type PropertyName

type PropertyName string

type Readable

type Readable string

type Reference

type Reference struct {
	URI         URI      `json:"$ref"`
	Summary     Readable `json:"summary,omitempty"`
	Description Readable `json:"description,omitempty"`
}

type Registry

type Registry interface {
	Lookup(string, string) *Schema
	Register(string, string, *Schema)
}

type RequestBody

type RequestBody struct {
	Description Readable                  `json:"description,omitempty"`
	Content     map[ContentType]MediaType `json:"content"`
	Required    bool                      `json:"required,omitempty"`
}

type Response

type Response struct {
	Description Readable                  `json:"description"`
	Headers     map[string]*Header        `json:"headers,omitempty"`
	Content     map[ContentType]MediaType `json:"content,omitempty"`
	Links       map[string]*Link          `json:"links,omitempty"`
}

type ResponseKey

type ResponseKey xyz.Switch[string, struct {
	Default ResponseKey `json:"default"`
}]

type Schema

type Schema struct {
	ID  URI `json:"$id,omitempty"`
	Ref URI `json:"$ref,omitempty"`

	Defs map[string]*Schema `json:"$defs,omitempty"`

	Dialect URI    `json:"$schema,omitempty"`
	Anchor  string `json:"$anchor,omitempty"`

	AllOf []*Schema `json:"allOf,omitempty"`
	AnyOf []*Schema `json:"anyOf,omitempty"`
	OneOf []*Schema `json:"oneOf,omitempty"`
	Not   *Schema   `json:"not,omitempty"`

	Type TypeSet `json:"type,omitempty"`

	Title             Readable                        `json:"title,omitempty"`
	Description       Readable                        `json:"description,omitempty"`
	Properties        map[PropertyName]*Schema        `json:"properties,omitempty"`
	Required          []PropertyName                  `json:"required,omitempty"`
	DependentRequired map[PropertyName][]PropertyName `json:"dependentRequired,omitempty"`

	DependentSchemas map[PropertyName]*Schema `json:"dependentSchemas,omitempty"`

	If   *Schema `json:"if,omitempty"`
	Then *Schema `json:"then,omitempty"`
	Else *Schema `json:"else,omitempty"`

	MinLength  int     `json:"minLength,omitempty"`
	MaxLength  int     `json:"maxLength,omitempty"`
	MultipleOf float64 `json:"multipleOf,omitempty"`

	Default json.RawMessage `json:"default,omitempty"`

	Minimum *float64 `json:"minimum,omitempty"`
	Maximum *float64 `json:"maximum,omitempty"`

	ExclusiveMinimum float64 `json:"exclusiveMinimum,omitempty"`
	ExclusiveMaximum float64 `json:"exclusiveMaximum,omitempty"`

	Const       json.RawMessage   `json:"const,omitempty"`
	Enum        []json.RawMessage `json:"enum,omitempty"`
	PrefixItems []*Schema         `json:"prefixItems,omitempty"`

	Contains    *Schema `json:"contains,omitempty"`
	MinContains int     `json:"minContains,omitempty"`
	MaxContains int     `json:"maxContains,omitempty"`

	MinItems    int  `json:"minItems,omitempty"`
	MaxItems    int  `json:"maxItems,omitempty"`
	UniqueItems bool `json:"uniqueItems,omitempty"`

	Pattern           string             `json:"pattern,omitempty"`
	PatternProperties map[string]*Schema `json:"patternProperties,omitempty"`
	PropertyNames     *Schema            `json:"propertyNames,omitempty"`

	MinProperties int `json:"minProperties,omitempty"`
	MaxProperties int `json:"maxProperties,omitempty"`

	Items *Schema `json:"items,omitempty"`

	Format *Format `json:"format,omitempty"`

	AdditionalProperties *Schema `json:"additionalProperties,omitempty"`

	ReadOnly  bool `json:"readOnly,omitempty"`
	WriteOnly bool `json:"writeOnly,omitempty"`

	Deprecated bool `json:"deprecated,omitempty"`

	ContentMediaType ContentType `json:"contentMediaType,omitempty"`
	ContentEncoding  string      `json:"contentEncoding,omitempty"`

	Discriminator         *Discriminator         `json:"discriminator,omitempty"`
	XML                   *XML                   `json:"xml,omitempty"`
	ExternalDocumentation *ExternalDocumentation `json:"externalDocs,omitempty"`
	Example               json.RawMessage        `json:"example,omitempty"`
	Examples              []json.RawMessage      `json:"examples,omitempty"`
}

Schema based on https://json-schema.org/draft/2020-12/json-schema-core

func (*Schema) Lookup

func (schema *Schema) Lookup(namespace, name string) *Schema

func (*Schema) Register

func (schema *Schema) Register(namespace, name string, value *Schema)

type SecurityScheme

type SecurityScheme struct {
	Type         SecuritySchemeType `json:"type"`
	Description  Markdown           `json:"description,omitempty"`
	Name         string             `json:"name,omitempty"`
	In           ParameterLocation  `json:"in,omitempty"`
	Scheme       string             `json:"scheme,omitempty"`
	BearerFormat string             `json:"bearerFormat,omitempty"`
	Flows        *OauthFlows        `json:"flows,omitempty"`
	ConnectURL   URL                `json:"openIdConnectUrl,omitempty"`
}

type SecuritySchemeID

type SecuritySchemeID string

type SecuritySchemeType

type SecuritySchemeType xyz.Switch[string, struct {
	Key       SecuritySchemeType `json:"apiKey"`
	HTTP      SecuritySchemeType `json:"http"`
	MutualTLS SecuritySchemeType `json:"mutualTLS"`
	OAuth2    SecuritySchemeType `json:"oauth2"`
	OpenID    SecuritySchemeType `json:"openIdConnect"`
}]

type Server

type Server struct {
	URL         URL                       `json:"url"`
	Description Readable                  `json:"description,omitempty"`
	Variables   map[string]ServerVariable `json:"variables,omitempty"`
}

type ServerVariable

type ServerVariable struct {
	Enum        []string `json:"enum,omitempty"`
	Default     string   `json:"default"`
	Description Readable `json:"description,omitempty"`
}

type Tag

type Tag struct {
	Name                  Readable              `json:"name"`
	Description           Markdown              `json:"description,omitempty"`
	ExternalDocumentation ExternalDocumentation `json:"externalDocs,omitempty"`
}

type Type

type Type xyz.Switch[string, struct {
	String  Type `json:"string"`
	Number  Type `json:"number"`
	Integer Type `json:"integer"`
	Object  Type `json:"object"`
	Array   Type `json:"array"`
	Bool    Type `json:"boolean"`
	Null    Type `json:"null"`
}]

type TypeSet

type TypeSet []Type

func (TypeSet) MarshalJSON

func (t TypeSet) MarshalJSON() ([]byte, error)

func (*TypeSet) UnmarshalJSON

func (t *TypeSet) UnmarshalJSON(data []byte) error

type URI

type URI string

type URL

type URL string

type Version

type Version string

type XML

type XML struct {
	Name      string `json:"name,omitempty"`
	Namespace URI    `json:"namespace,omitempty"`
	Prefix    string `json:"prefix,omitempty"`
	Attribute bool   `json:"attribute,omitempty"`
	Wrapped   bool   `json:"wrapped,omitempty"`
}