openapiv3

Documentation

Index

• Constants
• func Validate(obj any, doc *DocumentCore) error
• type Components
• type ComponentsCore
• type Contact
• type ContactCore
• type Discriminator
• type DiscriminatorCore
• type Document
• type DocumentCore
  • func (d *DocumentCore) Validate() error
• type Encoding
• type EncodingCore
• type Example
• type ExampleCore
• type Extensible
  • func (e Extensible[T]) MarshalJSON() ([]byte, error)
• type Extensions
• type ExternalDocumentation
• type ExternalDocumentationCore
• type Header
• type HeaderCore
• type Info
• type InfoCore
• type ItemSpec
  • func (i *ItemSpec) MarshalJSON() ([]byte, error)
  • func (i *ItemSpec) MarshalYAML() (any, error)
• type License
• type LicenseCore
• type Link
• type LinkCore
• type MediaType
• type MediaTypeCore
• type OAuthFlow
• type OAuthFlowCore
• type OAuthFlows
• type OAuthFlowsCore
• type Operation
• type OperationCore
• type Parameter
• type ParameterCore
• type Path
• type PathCore
• type Ref
  • func (r Ref[T]) MarshalJSON() ([]byte, error)
  • func (r Ref[T]) MarshalYAML() (any, error)
• type Reference
• type RequestBody
• type RequestBodyCore
• type Response
• type ResponseCore
• type Schema
• type SchemaCore
• type SecurityScheme
• type SecuritySchemeCore
• type Server
• type ServerCore
• type ServerVariable
• type ServerVariableCore
• type Tag
• type TagCore
• type TypeSet
  • func (t TypeSet) MarshalJSON() ([]byte, error)
  • func (t TypeSet) MarshalYAML() (any, error)
• type Validator

Constants

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

const (
	ParameterInPath  = "path"
	ParameterInQuery = "query"
)

const (
	ParameterStyleSimple         = "simple"
	ParameterStyleSpaceDelimited = "spaceDelimited"
	ParameterStylePipeDelimited  = "pipeDelimited"
	ParameterStyleTabDelimited   = "tabDelimited"
)

const (
	Version = "3.1.0"
)

Functions

func Validate

func Validate(obj any, doc *DocumentCore) error

Validate runs through the validation requirements and enforces them.

Types

type Components

type Components = Extensible[ComponentsCore]

The following are type aliases to simplify references to these types.

type ComponentsCore

type ComponentsCore struct {
	Schemas         map[string]*Extensible[SchemaCore] `json:"schemas,omitempty" yaml:"schemas,omitempty"`
	Responses       map[string]*Ref[Response]          `json:"responses,omitempty" yaml:"responses,omitempty"`
	Parameters      map[string]*Ref[Parameter]         `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	Examples        map[string]*Ref[Example]           `json:"examples,omitempty" yaml:"examples,omitempty"`
	RequestBodies   map[string]*Ref[RequestBody]       `json:"requestBodies,omitempty" yaml:"requestBodies,omitempty"`
	Headers         map[string]*Ref[Header]            `json:"headers,omitempty" yaml:"headers,omitempty"`
	SecuritySchemes map[string]*Ref[SecurityScheme]    `json:"securitySchemes,omitempty" yaml:"securitySchemes,omitempty"`
	Links           map[string]*Ref[Link]              `json:"links,omitempty" yaml:"links,omitempty"`
}

type Contact

type Contact = Extensible[ContactCore]

The following are type aliases to simplify references to these types.

type ContactCore

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

type Discriminator

type Discriminator = Extensible[DiscriminatorCore]

The following are type aliases to simplify references to these types.

type DiscriminatorCore

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

type Document

type Document = Extensible[DocumentCore]

The following are type aliases to simplify references to these types.

type DocumentCore

type DocumentCore struct {
	OpenAPI               string                 `json:"openapi" yaml:"openapi"`
	Info                  *Info                  `json:"info" yaml:"info" validate:"required"`
	SchemaDialect         string                 `json:"jsonSchemaDialect,omitempty" yaml:"jsonSchemaDialect,omitempty"`
	Servers               []*Server              `json:"servers,omitempty" yaml:"servers,omitempty"`
	Paths                 map[string]*Path       `json:"paths,omitempty" yaml:"paths,omitempty"`
	Components            *Components            `json:"components,omitempty" yaml:"components,omitempty"`
	Security              []map[string][]string  `json:"security,omitempty" yaml:"security,omitempty"`
	Tags                  []*Tag                 `json:"tags,omitempty" yaml:"tags,omitempty"`
	ExternalDocumentation *ExternalDocumentation `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
}

DocumentCore is the OpenAPI top-level document.

func (*DocumentCore) Validate

func (d *DocumentCore) Validate() error

type Encoding

type Encoding = Extensible[EncodingCore]

The following are type aliases to simplify references to these types.

type EncodingCore

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

type Example

type Example = Extensible[ExampleCore]

The following are type aliases to simplify references to these types.

type ExampleCore

type ExampleCore struct {
	Summary       string `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description   string `json:"description,omitempty" yaml:"description,omitempty"`
	Value         any    `json:"value,omitempty" yaml:"value,omitempty"`
	ExternalValue string `json:"externalValue,omitempty" yaml:"externalValue,omitempty"`
}

type Extensible

type Extensible[T any] struct {
	Object     T          `yaml:",inline"`
	Extensions Extensions `yaml:",inline"`
}

func (Extensible[T]) MarshalJSON

func (e Extensible[T]) MarshalJSON() ([]byte, error)

type Extensions

type Extensions map[string]any

type ExternalDocumentation

type ExternalDocumentation = Extensible[ExternalDocumentationCore]

The following are type aliases to simplify references to these types.

type ExternalDocumentationCore

type ExternalDocumentationCore struct {
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	URL         string `json:"url" yaml:"url" validate:"required"`
}

type Header

type Header = Extensible[HeaderCore]

The following are type aliases to simplify references to these types.

type HeaderCore

type HeaderCore struct {
	Description     string                                   `json:"description,omitempty" yaml:"description,omitempty"`
	Required        bool                                     `json:"required,omitempty" yaml:"required,omitempty"`
	Deprecated      bool                                     `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	AllowEmptyValue bool                                     `json:"allowEmptyValue,omitempty" yaml:"allowEmptyValue,omitempty"`
	Style           string                                   `json:"style,omitempty" yaml:"style,omitempty"`
	Explode         bool                                     `json:"explode,omitempty" yaml:"explode,omitempty"`
	Schema          *Extensible[SchemaCore]                  `json:"schema,omitempty" yaml:"schema,omitempty"`
	Example         any                                      `json:"example,omitempty" yaml:"example,omitempty"`
	Examples        map[string]*Ref[Extensible[ExampleCore]] `json:"examples,omitempty" yaml:"examples,omitempty"`
	Content         map[string]*Extensible[MediaTypeCore]    `json:"content,omitempty" yaml:"content,omitempty"`
}

type Info

type Info = Extensible[InfoCore]

The following are type aliases to simplify references to these types.

type InfoCore

type InfoCore struct {
	Title          string   `json:"title" yaml:"title" validate:"required"`
	Summary        string   `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description    string   `json:"description,omitempty" yaml:"description,omitempty"`
	TermsOfService string   `json:"termsOfService,omitempty" yaml:"termsOfService,omitempty"`
	Contact        *Contact `json:"contact,omitempty" yaml:"contact,omitempty"`
	License        *License `json:"license,omitempty" yaml:"license,omitempty"`
	Version        string   `json:"version" yaml:"version" validate:"required"`
}

type ItemSpec

type ItemSpec struct {
	Schema *Schema
	Items  []*Schema
}

ItemSpec is used to generate correct "items" value in JSON schema. If Schema is defined, schema gets marshaled, otherwise, items list gets used.

func (*ItemSpec) MarshalJSON

func (i *ItemSpec) MarshalJSON() ([]byte, error)

func (*ItemSpec) MarshalYAML

func (i *ItemSpec) MarshalYAML() (any, error)

type License

type License = Extensible[LicenseCore]

The following are type aliases to simplify references to these types.

type LicenseCore

type LicenseCore struct {
	Name       string `json:"name" yaml:"name" validate:"required"`
	Identifier string `json:"identifier,omitempty" yaml:"identifier,omitempty"`
	URL        string `json:"url,omitempty" yaml:"url,omitempty"`
}

type Link

type Link = Extensible[LinkCore]

The following are type aliases to simplify references to these types.

type LinkCore

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

type MediaType

type MediaType = Extensible[MediaTypeCore]

The following are type aliases to simplify references to these types.

type MediaTypeCore

type MediaTypeCore struct {
	Schema   *Extensible[SchemaCore]                  `json:"schema,omitempty" yaml:"schema,omitempty"`
	Example  any                                      `json:"example,omitempty" yaml:"example,omitempty"`
	Examples map[string]*Ref[Extensible[ExampleCore]] `json:"examples,omitempty" yaml:"examples,omitempty"`
	Encoding map[string]*Extensible[EncodingCore]     `json:"encoding,omitempty" yaml:"encoding,omitempty"`
}

type OAuthFlow

type OAuthFlow = Extensible[OAuthFlowCore]

The following are type aliases to simplify references to these types.

type OAuthFlowCore

type OAuthFlowCore struct {
	AuthorizationURL string            `json:"authorizationUrl,omitempty" yaml:"authorizationUrl,omitempty"`
	TokenURL         string            `json:"tokenUrl,omitempty" yaml:"tokenUrl,omitempty"`
	RefreshURL       string            `json:"refreshUrl,omitempty" yaml:"refreshUrl,omitempty"`
	Scopes           map[string]string `json:"scopes,omitempty" yaml:"scopes,omitempty"`
}

type OAuthFlows

type OAuthFlows = Extensible[OAuthFlowsCore]

The following are type aliases to simplify references to these types.

type OAuthFlowsCore

type OAuthFlowsCore struct {
	Implicit          *OAuthFlow `json:"implicit,omitempty" yaml:"implicit,omitempty"`
	Password          *OAuthFlow `json:"password,omitempty" yaml:"password,omitempty"`
	ClientCredentials *OAuthFlow `json:"clientCredentials,omitempty" yaml:"clientCredentials,omitempty"`
	AuthorizationCode *OAuthFlow `json:"authorizationCode,omitempty" yaml:"authorizationCode,omitempty"`
}

type Operation

type Operation = Extensible[OperationCore]

The following are type aliases to simplify references to these types.

type OperationCore

type OperationCore struct {
	Tags         []string                  `json:"tags,omitempty" yaml:"tags,omitempty"`
	Summary      string                    `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description  string                    `json:"description,omitempty" yaml:"description,omitempty"`
	ExternalDocs *ExternalDocumentation    `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	OperationID  string                    `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	Parameters   []*Ref[Parameter]         `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	RequestBody  *Ref[RequestBody]         `json:"requestBody,omitempty" yaml:"requestBody,omitempty"`
	Responses    map[string]*Ref[Response] `json:"responses,omitempty" yaml:"responses,omitempty"`
	Deprecated   bool                      `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	Security     []map[string][]string     `json:"security,omitempty" yaml:"security,omitempty"`
	Servers      []*Server                 `json:"servers,omitempty" yaml:"servers,omitempty"`
}

type Parameter

type Parameter = Extensible[ParameterCore]

The following are type aliases to simplify references to these types.

type ParameterCore

type ParameterCore struct {
	Name            string                                   `json:"name,omitempty" yaml:"name,omitempty"`
	In              string                                   `json:"in,omitempty" yaml:"in,omitempty"`
	Description     string                                   `json:"description,omitempty" yaml:"description,omitempty"`
	Required        bool                                     `json:"required,omitempty" yaml:"required,omitempty"`
	Deprecated      bool                                     `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	AllowEmptyValue bool                                     `json:"allowEmptyValue,omitempty" yaml:"allowEmptyValue,omitempty"`
	AllowReserved   bool                                     `json:"allowReserved,omitempty" yaml:"allowReserved,omitempty"`
	Style           string                                   `json:"style,omitempty" yaml:"style,omitempty"`
	Explode         bool                                     `json:"explode,omitempty" yaml:"explode,omitempty"`
	Schema          *Extensible[SchemaCore]                  `json:"schema,omitempty" yaml:"schema,omitempty"`
	Example         any                                      `json:"example,omitempty" yaml:"example,omitempty"`
	Examples        map[string]*Ref[Extensible[ExampleCore]] `json:"examples,omitempty" yaml:"examples,omitempty"`
	Content         map[string]*Extensible[MediaTypeCore]    `json:"content,omitempty" yaml:"content,omitempty"`
}

type Path

type Path = Extensible[PathCore]

The following are type aliases to simplify references to these types.

type PathCore

type PathCore struct {
	Summary     string         `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description string         `json:"description,omitempty" yaml:"description,omitempty"`
	Get         *Operation     `json:"get,omitempty" yaml:"get,omitempty"`
	Put         *Operation     `json:"put,omitempty" yaml:"put,omitempty"`
	Post        *Operation     `json:"post,omitempty" yaml:"post,omitempty"`
	Delete      *Operation     `json:"delete,omitempty" yaml:"delete,omitempty"`
	Options     *Operation     `json:"options,omitempty" yaml:"options,omitempty"`
	Head        *Operation     `json:"head,omitempty" yaml:"head,omitempty"`
	Patch       *Operation     `json:"patch,omitempty" yaml:"patch,omitempty"`
	Trace       *Operation     `json:"trace,omitempty" yaml:"trace,omitempty"`
	Servers     []*Server      `json:"servers,omitempty" yaml:"servers,omitempty"`
	Parameters  []*Ref[Server] `json:"parameters,omitempty" yaml:"parameters,omitempty"`
}

type Ref

type Ref[T any] struct {
	Data      T
	Reference *Reference
}

Ref is a container that allows either using a reference or data.

func (Ref[T]) MarshalJSON

func (r Ref[T]) MarshalJSON() ([]byte, error)

func (Ref[T]) MarshalYAML

func (r Ref[T]) MarshalYAML() (any, error)

type Reference

type Reference struct {
	Ref         string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
	Summary     string `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

type RequestBody

type RequestBody = Extensible[RequestBodyCore]

The following are type aliases to simplify references to these types.

type RequestBodyCore

type RequestBodyCore struct {
	Description string                                `json:"description,omitempty" yaml:"description,omitempty"`
	Content     map[string]*Extensible[MediaTypeCore] `json:"content,omitempty" yaml:"content,omitempty"`
	Required    bool                                  `json:"required,omitempty" yaml:"required,omitempty"`
}

type Response

type Response = Extensible[ResponseCore]

The following are type aliases to simplify references to these types.

type ResponseCore

type ResponseCore struct {
	Description string                                  `json:"description,omitempty" yaml:"description,omitempty"`
	Headers     map[string]*Ref[Extensible[HeaderCore]] `json:"headers,omitempty" yaml:"headers,omitempty"`
	Content     map[string]*Extensible[MediaTypeCore]   `json:"content,omitempty" yaml:"content,omitempty"`
	Links       map[string]*Ref[Extensible[LinkCore]]   `json:"links,omitempty" yaml:"links,omitempty"`
}

type Schema

type Schema = Extensible[SchemaCore]

The following are type aliases to simplify references to these types.

type SchemaCore

type SchemaCore struct {
	Discriminator         *Discriminator         `json:"discriminator,omitempty" yaml:"discriminator,omitempty"`
	ExternalDocumentation *ExternalDocumentation `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	Ref                   string                 `json:"$ref,omitempty" yaml:"$ref,omitempty"`
	Schema                string                 `json:"$schema,omitempty" yaml:"$schema,omitempty"`

	Title                string             `json:"title,omitempty" yaml:"title,omitempty"`
	Pattern              string             `json:"pattern,omitempty" yaml:"pattern,omitempty"`
	Required             []string           `json:"required,omitempty" yaml:"required,omitempty"`
	Enum                 []string           `json:"enum,omitempty" yaml:"enum,omitempty"`
	MultipleOf           float64            `json:"multipleOf,omitempty" yaml:"multipleOf,omitempty"`
	Maximum              float64            `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	ExclusiveMaximum     float64            `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`
	Minimum              float64            `json:"minimum,omitempty" yaml:"minimum,omitempty"`
	ExclusiveMinimum     float64            `json:"exclusiveMinimum,omitempty" yaml:"exclusiveMinimum,omitempty"`
	MaxLength            uint64             `json:"maxLength,omitempty" yaml:"maxLength,omitempty"`
	MinLength            uint64             `json:"minLength,omitempty" yaml:"minLength,omitempty"`
	MaxItems             uint64             `json:"maxItems,omitempty" yaml:"maxItems,omitempty"`
	MinItems             uint64             `json:"minItems,omitempty" yaml:"minItems,omitempty"`
	UniqueItems          bool               `json:"uniqueItems,omitempty" yaml:"uniqueItems,omitempty"`
	MaxProperties        uint64             `json:"maxProperties,omitempty" yaml:"maxProperties,omitempty"`
	MinProperties        uint64             `json:"minProperties,omitempty" yaml:"minProperties,omitempty"`
	Type                 TypeSet            `json:"type,omitempty" yaml:"type,omitempty"`
	Description          string             `json:"description,omitempty" yaml:"description,omitempty"`
	Items                *ItemSpec          `json:"items,omitempty" yaml:"items,omitempty"`
	Properties           map[string]*Schema `json:"properties,omitempty" yaml:"properties,omitempty"`
	AdditionalProperties *Schema            `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"`
	Default              any                `json:"default,omitempty" yaml:"default,omitempty"`
	AllOf                []*Schema          `json:"allOf,omitempty" yaml:"allOf,omitempty"`
	AnyOf                []*Schema          `json:"anyOf,omitempty" yaml:"anyOf,omitempty"`
	OneOf                []*Schema          `json:"oneOf,omitempty" yaml:"oneOf,omitempty"`
	Not                  *Schema            `json:"not,omitempty" yaml:"not,omitempty"`
	ReadOnly             bool               `json:"readOnly,omitempty" yaml:"readOnly,omitempty"`
	WriteOnly            bool               `json:"writeOnly,omitempty" yaml:"writeOnly,omitempty"`
	Examples             []any              `json:"examples,omitempty" yaml:"examples,omitempty"`
	Format               string             `json:"format,omitempty" yaml:"format,omitempty"`
	Deprecated           bool               `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
}

type SecurityScheme

type SecurityScheme = Extensible[SecuritySchemeCore]

The following are type aliases to simplify references to these types.

type SecuritySchemeCore

type SecuritySchemeCore struct {
	Type             string      `json:"type,omitempty" yaml:"type,omitempty"`
	Description      string      `json:"description,omitempty" yaml:"description,omitempty"`
	Name             string      `json:"name,omitempty" yaml:"name,omitempty"`
	In               string      `json:"in,omitempty" yaml:"in,omitempty"`
	Scheme           string      `json:"scheme,omitempty" yaml:"scheme,omitempty"`
	BearerFormat     string      `json:"bearerFormat,omitempty" yaml:"bearerFormat,omitempty"`
	Flows            *OAuthFlows `json:"flows,omitempty" yaml:"flows,omitempty"`
	OpenIDConnectURL string      `json:"openIdConnectUrl,omitempty" yaml:"openIdConnectUrl,omitempty"`
}

type Server

type Server = Extensible[ServerCore]

The following are type aliases to simplify references to these types.

type ServerCore

type ServerCore struct {
	URL         string                    `json:"url" yaml:"url" validate:"required"`
	Description string                    `json:"description,omitempty" yaml:"description,omitempty"`
	Variables   map[string]ServerVariable `json:"variables,omitempty" yaml:"variables,omitempty"`
}

type ServerVariable

type ServerVariable = Extensible[ServerVariableCore]

The following are type aliases to simplify references to these types.

type ServerVariableCore

type ServerVariableCore struct {
	Enum        []string `json:"enum,omitempty" yaml:"enum,omitempty"`
	Default     string   `json:"default" yaml:"default" validate:"required"`
	Description string   `json:"description,omitempty" yaml:"description,omitempty"`
}

type Tag

type Tag = Extensible[TagCore]

The following are type aliases to simplify references to these types.

type TagCore

type TagCore struct {
	Name         string                 `json:"name" yaml:"name" validate:"required"`
	Description  string                 `json:"description,omitempty" yaml:"description,omitempty"`
	ExternalDocs *ExternalDocumentation `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
}

type TypeSet

type TypeSet []string

func (TypeSet) MarshalJSON

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

func (TypeSet) MarshalYAML

func (t TypeSet) MarshalYAML() (any, error)

type Validator

type Validator interface {
	// Validate takes the entire document in case it is needed to look up references.
	Validate(*DocumentCore) error
}

Validator can be used to validate individual objects.