oas

Documentation

Index

• type AuthorizationCodeOAuthFlow
• type Callback
  • func (c Callback) MarshalJSON() ([]byte, error)
  • func (c *Callback) UnmarshalJSON(b []byte) error
• type ClientCredentialsOAuthFlow
• type Components
• type Contact
• type DataType
• type Discriminator
• type Encoding
• type Example
• type ExternalDocumentation
• type Format
• type Header
• type ImplicitOAuthFlow
• type Info
• type License
• type Link
• type Location
  • func (l Location) MarshalJSON() ([]byte, error)
  • func (l Location) String() string
  • func (l *Location) UnmarshalJSON(b []byte) error
• type MediaType
• type OAuthFlows
• type OpenAPI
  • func Default() OpenAPI
  • func New(filename string) (*OpenAPI, error)
  • func (doc *OpenAPI) IterSchema() iter.Seq[*oas31.Schema]
  • func (doc *OpenAPI) Validate() error
• type Operation
• type Parameter
• type PasswordOAuthFlow
• type PathItem
  • func (i *PathItem) Range() map[string]Operation
• type Paths
• type RequestBody
• type Response
• type Responses
  • func (r Responses) Validate() error
• type RichText
• type RuntimeExpression
• type Schema
• type Scheme
  • func (s Scheme) MarshalJSON() ([]byte, error)
  • func (s Scheme) String() string
  • func (s *Scheme) UnmarshalJSON(b []byte) error
• type SecurityRequirement
• type SecurityScheme
• type SemanticVersion
  • func (v SemanticVersion) Validate() error
• type Server
• type ServerVariable
• type SpecificationExtension
• type Style
  • func (s Style) MarshalJSON() ([]byte, error)
  • func (s Style) String() string
  • func (s *Style) UnmarshalJSON(b []byte) error
• type Tag
• type Type
• type UrlTemplate
• type XML

Types

type AuthorizationCodeOAuthFlow

type AuthorizationCodeOAuthFlow struct {
	// contains filtered or unexported fields
}

type Callback

type Callback struct {
	draft2020.ReferenceMixin[Callback]
	Value map[RuntimeExpression]PathItem
}

func (Callback) MarshalJSON

func (c Callback) MarshalJSON() ([]byte, error)

func (*Callback) UnmarshalJSON

func (c *Callback) UnmarshalJSON(b []byte) error

type ClientCredentialsOAuthFlow

type ClientCredentialsOAuthFlow struct {
	// contains filtered or unexported fields
}

type Components

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

type Contact

type Contact struct {
	Name       string                 `json:"name,omitempty"`
	Url        string                 `json:"url,omitempty" validate:"omitempty,url"`
	Email      string                 `json:"email,omitempty" validate:"omitempty,email"`
	Extensions SpecificationExtension `json:"-"`
}

type DataType

type DataType struct {
	Type   jsonschema.Type `json:"type" validate:"required"`
	Format Format          `json:"format,omitempty"`
}

type Discriminator

type Discriminator = oas31.Discriminator

type Encoding

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

type Example

type Example struct {
	draft2020.ReferenceMixin[Example]
	Summary       string                 `json:"summary,omitempty"`
	Description   RichText               `json:"description,omitempty"`
	Value         interface{}            `json:"value,omitempty" validate:"excluded_with=ExternalValue"`
	ExternalValue string                 `json:"externalValue,omitempty" validate:"excluded_with=Value"`
	Extensions    SpecificationExtension `json:"-"`
}

type ExternalDocumentation

type ExternalDocumentation = oas31.ExternalDocumentation

type Format

type Format = jsonschema.Format

const (
	Int32Format  Format = "int32"
	Int64Format  Format = "int64"
	FloatFormat  Format = "float"
	DoubleFormat Format = "double"

	Base64Format   Format = "base64"   // base64 encoded characters
	BinaryFormat   Format = "binary"   // octet-stream
	PasswordFormat Format = "password" // A hint to UIs to obscure input.
)

type Header

type Header struct {
	draft2020.ReferenceMixin[Header]
	Description     RichText               `json:"description,omitempty"`
	Required        bool                   `json:"required,omitempty" validate:"required_if=In path"`
	Deprecated      bool                   `json:"deprecated,omitempty"`
	AllowEmptyValue bool                   `json:"allowEmptyValue,omitempty"` // Deprecated
	Style           Style                  `json:"style,omitempty"`
	Explode         *bool                  `json:"explode,omitempty"`
	AllowReserved   bool                   `json:"allowReserved,omitempty"`
	Schema          *oas31.Schema          `json:"schema,omitempty" validate:"required_without=Content"`
	Content         map[string]MediaType   `json:"content,omitempty" validate:"required_without=Schema"`
	Example         interface{}            `json:"example,omitempty"`
	Examples        map[string]Example     `json:"examples,omitempty"`
	Extensions      SpecificationExtension `json:"-"`
}

type ImplicitOAuthFlow

type ImplicitOAuthFlow struct {
	// contains filtered or unexported fields
}

type Info

type Info struct {
	Title          string                 `json:"title,omitempty" validate:"required"`
	Description    RichText               `json:"description,omitempty"`
	TermsOfService string                 `json:"termsOfService,omitempty" validate:"omitempty,url"`
	Contact        *Contact               `json:"contact,omitempty"`
	License        *License               `json:"license,omitempty"`
	Version        string                 `json:"version,omitempty" validate:"required"`
	Extensions     SpecificationExtension `json:"-"`
}

Info provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.

type License

type License struct {
	Name       string                 `json:"name,omitempty" validate:"required"`
	Url        string                 `json:"url,omitempty" validate:"url,omitempty"`
	Extensions SpecificationExtension `json:"-"`
}

type Link

type Link struct {
	draft2020.ReferenceMixin[Link]
	OperationRef string                 `json:"operationRef,omitempty" validate:"required_without=OperationId"`
	OperationId  string                 `json:"operationId,omitempty" validate:"required_without=OperationRef"`
	Parameters   map[string]interface{} `json:"parameters,omitempty"`
	RequestBody  []interface{}          `json:"requestBody,omitempty"`
	Description  string                 `json:"description,omitempty"`
	Server       string                 `json:"server,omitempty"`
	Extensions   SpecificationExtension `json:"-"`
}

type Location

type Location int8

const (
	QueryLocation Location = iota + 1
	HeaderLocation
	PathLocation
	CookieLocation
)

func (Location) MarshalJSON

func (l Location) MarshalJSON() ([]byte, error)

func (Location) String

func (l Location) String() string

func (*Location) UnmarshalJSON

func (l *Location) UnmarshalJSON(b []byte) error

type MediaType

type MediaType struct {
	Schema     Schema                 `json:"schema,omitempty"`
	Example    interface{}            `json:"example,omitempty"`
	Examples   map[string]Example     `json:"examples,omitempty"`
	Encoding   map[string]Encoding    `json:"encoding,omitempty"`
	Extensions SpecificationExtension `json:"-"`
}

type OAuthFlows

type OAuthFlows struct {
	Implicit          *ImplicitOAuthFlow          `json:"implicit,omitempty"`
	Password          *PasswordOAuthFlow          `json:"password,omitempty"`
	ClientCredentials *ClientCredentialsOAuthFlow `json:"clientCredentials,omitempty"`
	AuthorizationCode *AuthorizationCodeOAuthFlow `json:"authorizationCode,omitempty"`
	Extensions        SpecificationExtension      `json:"-"`
}

type OpenAPI

type OpenAPI struct {
	Version      SemanticVersion              `json:"openapi,omitempty" validate:"required"`
	Info         Info                         `json:"info,omitempty" validate:"required"`
	Servers      []Server                     `json:"servers,omitempty" validate:"dive"`
	Paths        Paths                        `json:"paths,omitempty" validate:"dive"`
	Webhooks     map[string]PathItem          `json:"webhooks,omitempty" validate:"dive"`
	Components   Components                   `json:"components,omitempty"`
	Security     []SecurityRequirement        `json:"security,omitempty" validate:"dive"`
	Tags         []Tag                        `json:"tags,omitempty" validate:"dive"`
	ExternalDocs *oas31.ExternalDocumentation `json:"externalDocs,omitempty"`
	Extensions   SpecificationExtension       `json:"-"`
}

func Default

func Default() OpenAPI

Default returns a minimal starting OpenAPI specs.

func New

func New(filename string) (*OpenAPI, error)

func (*OpenAPI) IterSchema

func (doc *OpenAPI) IterSchema() iter.Seq[*oas31.Schema]

func (*OpenAPI) Validate

func (doc *OpenAPI) Validate() error

type Operation

type Operation struct {
	Tags         []string                     `json:"tags,omitempty"`
	Summary      string                       `json:"summary,omitempty"`
	Description  RichText                     `json:"description,omitempty"`
	ExternalDocs *oas31.ExternalDocumentation `json:"externalDocs,omitempty"`
	OperationId  string                       `json:"operationId,omitempty"`
	Parameters   []Parameter                  `json:"parameters,omitempty" validate:"dive"`
	RequestBody  *RequestBody                 `json:"requestBody,omitempty"`
	Responses    Responses                    `json:"responses,omitempty" validate:"dive"`
	Callbacks    map[string]Callback          `json:"callbacks,omitempty" validate:"dive"`
	Deprecated   bool                         `json:"deprecated,omitempty"`
	Security     []SecurityRequirement        `json:"security,omitempty" validate:"dive"`
	Servers      []Server                     `json:"servers,omitempty" validate:"dive"`
	Extensions   SpecificationExtension       `json:"-"`
}

type Parameter

type Parameter struct {
	draft2020.ReferenceMixin[Parameter]
	Name            string                 `json:"name,omitempty" validate:"required"`
	In              Location               `json:"in,omitempty" validate:"required"`
	Description     RichText               `json:"description,omitempty"`
	Required        bool                   `json:"required,omitempty" validate:"required_if=In 3"`
	Deprecated      bool                   `json:"deprecated,omitempty"`
	AllowEmptyValue bool                   `json:"allowEmptyValue,omitempty"` // Deprecated
	Style           Style                  `json:"style,omitempty"`
	Explode         *bool                  `json:"explode,omitempty"`
	AllowReserved   bool                   `json:"allowReserved,omitempty"`
	Schema          Schema                 `json:"schema,omitempty" validate:"required_without=Content"`
	Content         map[string]MediaType   `json:"content,omitempty" validate:"required_without=Schema"`
	Example         interface{}            `json:"example,omitempty"`
	Examples        map[string]Example     `json:"examples,omitempty"`
	Extensions      SpecificationExtension `json:"-"`
}

type PasswordOAuthFlow

type PasswordOAuthFlow struct {
	// contains filtered or unexported fields
}

type PathItem

type PathItem struct {
	draft2020.ReferenceMixin[PathItem]
	Ref         string                 `json:"$ref,omitempty" validate:"omitempty,uri"`
	Summary     string                 `json:"summary,omitempty"`
	Description RichText               `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"`
	Extensions  SpecificationExtension `json:"-"`
}

func (*PathItem) Range

func (i *PathItem) Range() map[string]Operation

type Paths

type Paths map[string]PathItem

type RequestBody

type RequestBody struct {
	draft2020.ReferenceMixin[RequestBody]
	Description RichText               `json:"description,omitempty"`
	Content     map[string]MediaType   `json:"content,omitempty" validate:"required"`
	Required    bool                   `json:"required,omitempty"`
	Extensions  SpecificationExtension `json:"-"`
}

type Response

type Response struct {
	draft2020.ReferenceMixin[Response]
	Description RichText               `json:"description,omitempty" validate:"required"`
	Headers     map[string]Header      `json:"headers,omitempty"`
	Content     map[string]MediaType   `json:"content,omitempty"`
	Links       map[string]Link        `json:"links,omitempty"`
	Extensions  SpecificationExtension `json:"-"`
}

type Responses

type Responses map[string]Response

func (Responses) Validate

func (r Responses) Validate() error

type RichText

type RichText string

RichText supports CommonMark markdown formatting.

type RuntimeExpression

type RuntimeExpression string

type Schema

type Schema = oas31.Schema

type Scheme

type Scheme int8

const (
	ApiKeyScheme Scheme = iota + 1
	HttpScheme
	MutualTLSScheme
	OAuth2Scheme
	OpenIdConnectScheme
)

func (Scheme) MarshalJSON

func (s Scheme) MarshalJSON() ([]byte, error)

func (Scheme) String

func (s Scheme) String() string

func (*Scheme) UnmarshalJSON

func (s *Scheme) UnmarshalJSON(b []byte) error

type SecurityRequirement

type SecurityRequirement map[string][]string

type SecurityScheme

type SecurityScheme struct {
	Type             Scheme                 `json:"type,omitempty" validate:"required"`
	Description      RichText               `json:"description,omitempty"`
	Name             string                 `json:"name,omitempty"  validate:"required_if=Type 1,excluded_unless=Type 1"`
	In               Location               `json:"in,omitempty"  validate:"required_if=Type 1,excluded_unless=Type 1,omitempty,oneof=1 2 4"`
	Scheme           iana.AuthScheme        `json:"scheme,omitempty" validate:"required_if=Type 2,excluded_unless=Type 2"`
	BearerFormat     string                 `json:"bearerFormat,omitempty" validate:"excluded_unless=Scheme bearer"`
	Flows            *OAuthFlows            `json:"flows,omitempty" validate:"required_if=Type 4,excluded_unless=Type 4"`
	OpenIdConnectUrl string                 `json:"openIdConnectUrl,omitempty" validate:"required_if=Type 5,excluded_unless=Type 5,omitempty,url"`
	Extensions       SpecificationExtension `json:"-"`
}

type SemanticVersion

type SemanticVersion string

func (SemanticVersion) Validate

func (v SemanticVersion) Validate() error

type Server

type Server struct {
	Url         UrlTemplate               `json:"url,omitempty" validate:"required"`
	Description RichText                  `json:"description,omitempty"`
	Variables   map[string]ServerVariable `json:"variables,omitempty" validate:"dive"`
	Extensions  SpecificationExtension    `json:"-"`
}

type ServerVariable

type ServerVariable struct {
	Enum        []string               `json:"enum,omitempty" validate:"min=1"`
	Default     string                 `json:"default,omitempty" validate:"required"`
	Description RichText               `json:"description,omitempty"`
	Extensions  SpecificationExtension `json:"-"`
}

type SpecificationExtension

type SpecificationExtension = oas31.SpecificationExtension

SpecificationExtension properties are implemented as patterned fields that are always prefixed by "x-".

type Style

type Style int8

const (
	MatrixStyle Style = iota + 1
	LabelStyle
	FormStyle
	SimpleStyle
	SpaceDelimitedStyle
	PipeDelimitedStyle
	DeepObjectStyle
)

func (Style) MarshalJSON

func (s Style) MarshalJSON() ([]byte, error)

func (Style) String

func (s Style) String() string

func (*Style) UnmarshalJSON

func (s *Style) UnmarshalJSON(b []byte) error

type Tag

type Tag struct {
	Name         string                       `json:"name,omitempty" validate:"required"`
	Description  RichText                     `json:"description,omitempty"`
	ExternalDocs *oas31.ExternalDocumentation `json:"externalDocs,omitempty"`
	Extensions   SpecificationExtension       `json:"-"`
}

type Type

type Type = jsonschema.Type

type UrlTemplate

type UrlTemplate string

UrlTemplate supports ServerVariable and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.

type XML

type XML = oas31.XML