v3

package
v0.15.13 Latest Latest
Warning

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

Go to latest
Published: Feb 21, 2024 License: MIT Imports: 17 Imported by: 50

Documentation

Overview

Package v3 represents all OpenAPI 3+ high-level models. High-level models are easy to navigate and simple to extract what ever is required from an OpenAPI 3+ specification.

High-level models are backed by low-level ones. There is a 'GoLow()' method available on every high level object. 'Going Low' allows engineers to transition from a high-level or 'porcelain' API, to a low-level 'plumbing' API, which provides fine grain detail to the underlying AST powering the data, lines, columns, raw nodes etc.

Example (CreateHighLevelOpenAPIDocument)

An example of how to create a new high-level OpenAPI 3+ document from an OpenAPI specification.

// Load in an OpenAPI 3+ specification as a byte slice.
data, _ := os.ReadFile("../../../test_specs/petstorev3.json")

// Create a new *datamodel.SpecInfo from bytes.
info, _ := datamodel.ExtractSpecInfo(data)

var err error

// Create a new low-level Document, capture any errors thrown during creation.
lowDoc, err = lowv3.CreateDocumentFromConfig(info, datamodel.NewDocumentConfiguration())

// Get upset if any errors were thrown.
for i := range utils.UnwrapErrors(err) {
	fmt.Printf("error: %v", i)
}

// Create a high-level Document from the low-level one.
doc := NewDocument(lowDoc)

// Print out some details
fmt.Printf("Petstore contains %d paths and %d component schemas",
	orderedmap.Len(doc.Paths.PathItems), orderedmap.Len(doc.Components.Schemas))
Output:

Petstore contains 13 paths and 8 component schemas

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExtractContent

ExtractContent takes in a complex and hard to navigate low-level content map, and converts it in to a much simpler and easier to navigate high-level one.

func ExtractEncoding

ExtractEncoding converts hard to navigate low-level plumbing Encoding definitions, into a high-level simple map

func ExtractHeaders

ExtractHeaders will extract a hard to navigate low-level Header map, into simple high-level one.

Types

type Callback

type Callback struct {
	Expression *orderedmap.Map[string, *PathItem]  `json:"-" yaml:"-"`
	Extensions *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

Callback represents a high-level Callback object for OpenAPI 3+.

A map of possible out-of band callbacks related to the parent operation. Each value in the map is a PathItem Object that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the path item object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.

func NewCallback

func NewCallback(lowCallback *low.Callback) *Callback

NewCallback creates a new high-level callback from a low-level one.

func (*Callback) GoLow

func (c *Callback) GoLow() *low.Callback

GoLow returns the low-level Callback instance used to create the high-level one.

func (*Callback) GoLowUntyped added in v0.7.0

func (c *Callback) GoLowUntyped() any

GoLowUntyped will return the low-level Callback instance that was used to create the high-level one, with no type

func (*Callback) MarshalYAML added in v0.7.0

func (c *Callback) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the Paths object.

func (*Callback) MarshalYAMLInline added in v0.14.0

func (c *Callback) MarshalYAMLInline() (interface{}, error)

func (*Callback) Render added in v0.7.0

func (c *Callback) Render() ([]byte, error)

Render will return a YAML representation of the Callback object as a byte slice.

func (*Callback) RenderInline added in v0.14.0

func (c *Callback) RenderInline() ([]byte, error)

RenderInline will return an YAML representation of the Callback object as a byte slice with references resolved.

type Components

type Components struct {
	Schemas         *orderedmap.Map[string, *highbase.SchemaProxy] `json:"schemas,omitempty" yaml:"schemas,omitempty"`
	Responses       *orderedmap.Map[string, *Response]             `json:"responses,omitempty" yaml:"responses,omitempty"`
	Parameters      *orderedmap.Map[string, *Parameter]            `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	Examples        *orderedmap.Map[string, *highbase.Example]     `json:"examples,omitempty" yaml:"examples,omitempty"`
	RequestBodies   *orderedmap.Map[string, *RequestBody]          `json:"requestBodies,omitempty" yaml:"requestBodies,omitempty"`
	Headers         *orderedmap.Map[string, *Header]               `json:"headers,omitempty" yaml:"headers,omitempty"`
	SecuritySchemes *orderedmap.Map[string, *SecurityScheme]       `json:"securitySchemes,omitempty" yaml:"securitySchemes,omitempty"`
	Links           *orderedmap.Map[string, *Link]                 `json:"links,omitempty" yaml:"links,omitempty"`
	Callbacks       *orderedmap.Map[string, *Callback]             `json:"callbacks,omitempty" yaml:"callbacks,omitempty"`
	Extensions      *orderedmap.Map[string, *yaml.Node]            `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

Components represents a high-level OpenAPI 3+ Components Object, that is backed by a low-level one.

Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.

func NewComponents

func NewComponents(comp *low.Components) *Components

NewComponents will create new high-level instance of Components from a low-level one. Components can be considerable in scope, with a lot of different properties across different categories. All components are built asynchronously in order to keep things fast.

func (*Components) GoLow

func (c *Components) GoLow() *low.Components

GoLow returns the low-level Components instance used to create the high-level one.

func (*Components) MarshalYAML added in v0.7.0

func (c *Components) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the Response object.

func (*Components) Render added in v0.7.0

func (c *Components) Render() ([]byte, error)

Render will return a YAML representation of the Components object as a byte slice.

type Document

type Document struct {
	// Version is the version of OpenAPI being used, extracted from the 'openapi: x.x.x' definition.
	// This is not a standard property of the OpenAPI model, it's a convenience mechanism only.
	Version string `json:"openapi,omitempty" yaml:"openapi,omitempty"`

	// Info represents a specification Info definitions
	// Provides metadata about the API. The metadata MAY be used by tooling as required.
	// - https://spec.openapis.org/oas/v3.1.0#info-object
	Info *base.Info `json:"info,omitempty" yaml:"info,omitempty"`

	// Servers is a slice of Server instances which provide connectivity information to a target server. If the servers
	// property is not provided, or is an empty array, the default value would be a Server Object with an url value of /.
	// - https://spec.openapis.org/oas/v3.1.0#server-object
	Servers []*Server `json:"servers,omitempty" yaml:"servers,omitempty"`

	// Paths contains all the PathItem definitions for the specification.
	// The available paths and operations for the API, The most important part of ths spec.
	// - https://spec.openapis.org/oas/v3.1.0#paths-object
	Paths *Paths `json:"paths,omitempty" yaml:"paths,omitempty"`

	// Components is an element to hold various schemas for the document.
	// - https://spec.openapis.org/oas/v3.1.0#components-object
	Components *Components `json:"components,omitempty" yaml:"components,omitempty"`

	// Security contains global security requirements/roles for the specification
	// A declaration of which security mechanisms can be used across the API. The list of values includes alternative
	// security requirement objects that can be used. Only one of the security requirement objects need to be satisfied
	// to authorize a request. Individual operations can override this definition. To make security optional,
	// an empty security requirement ({}) can be included in the array.
	// - https://spec.openapis.org/oas/v3.1.0#security-requirement-object
	Security []*base.SecurityRequirement `json:"security,omitempty" yaml:"security,omitempty"`

	// Tags is a slice of base.Tag instances defined by the specification
	// A list of tags used by the document with additional metadata. The order of the tags can be used to reflect on
	// their order by the parsing tools. Not all tags that are used by the Operation Object must be declared.
	// The tags that are not declared MAY be organized randomly or based on the tools’ logic.
	// Each tag name in the list MUST be unique.
	// - https://spec.openapis.org/oas/v3.1.0#tag-object
	Tags []*base.Tag `json:"tags,omitempty" yaml:"tags,omitempty"`

	// ExternalDocs is an instance of base.ExternalDoc for.. well, obvious really, innit.
	// - https://spec.openapis.org/oas/v3.1.0#external-documentation-object
	ExternalDocs *base.ExternalDoc `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`

	// Extensions contains all custom extensions defined for the top-level document.
	Extensions *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"`

	// JsonSchemaDialect is a 3.1+ property that sets the dialect to use for validating *base.Schema definitions
	// The default value for the $schema keyword within Schema Objects contained within this OAS document.
	// This MUST be in the form of a URI.
	// - https://spec.openapis.org/oas/v3.1.0#schema-object
	JsonSchemaDialect string `json:"jsonSchemaDialect,omitempty" yaml:"jsonSchemaDialect,omitempty"`

	// Webhooks is a 3.1+ property that is similar to callbacks, except, this defines incoming webhooks.
	// The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement.
	// Closely related to the callbacks feature, this section describes requests initiated other than by an API call,
	// for example by an out-of-band registration. The key name is a unique string to refer to each webhook,
	// while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider
	// and the expected responses. An example is available.
	Webhooks *orderedmap.Map[string, *PathItem] `json:"webhooks,omitempty" yaml:"webhooks,omitempty"`

	// Index is a reference to the *index.SpecIndex that was created for the document and used
	// as a guide when building out the Document. Ideal if further processing is required on the model and
	// the original details are required to continue the work.
	//
	// This property is not a part of the OpenAPI schema, this is custom to libopenapi.
	Index *index.SpecIndex `json:"-" yaml:"-"`

	// Rolodex is the low-level rolodex used when creating this document.
	// This in an internal structure and not part of the OpenAPI schema.
	Rolodex *index.Rolodex `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

Document represents a high-level OpenAPI 3 document (both 3.0 & 3.1). A Document is the root of the specification.

func NewDocument

func NewDocument(document *low.Document) *Document

NewDocument will create a new high-level Document from a low-level one.

func (*Document) GoLow

func (d *Document) GoLow() *low.Document

GoLow returns the low-level Document that was used to create the high level one.

func (*Document) MarshalYAML added in v0.7.0

func (d *Document) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the Document object.

func (*Document) MarshalYAMLInline added in v0.8.4

func (d *Document) MarshalYAMLInline() (interface{}, error)

func (*Document) Render added in v0.7.0

func (d *Document) Render() ([]byte, error)

Render will return a YAML representation of the Document object as a byte slice.

func (*Document) RenderInline added in v0.8.4

func (d *Document) RenderInline() ([]byte, error)

func (*Document) RenderJSON added in v0.9.0

func (d *Document) RenderJSON(indention string) []byte

RenderJSON will return a JSON representation of the Document object as a byte slice.

func (*Document) RenderWithIndention added in v0.9.0

func (d *Document) RenderWithIndention(indent int) []byte

RenderWithIndention will return a YAML representation of the Document object as a byte slice. the rendering will use the original indention of the document.

type Encoding

type Encoding struct {
	ContentType   string                           `json:"contentType,omitempty" yaml:"contentType,omitempty"`
	Headers       *orderedmap.Map[string, *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"`
	// contains filtered or unexported fields
}

Encoding represents an OpenAPI 3+ Encoding object

func NewEncoding

func NewEncoding(encoding *low.Encoding) *Encoding

NewEncoding creates a new instance of Encoding from a low-level one.

func (*Encoding) GoLow

func (e *Encoding) GoLow() *low.Encoding

GoLow returns the low-level Encoding instance used to create the high-level one.

func (*Encoding) GoLowUntyped added in v0.7.0

func (e *Encoding) GoLowUntyped() any

GoLowUntyped will return the low-level Encoding instance that was used to create the high-level one, with no type

func (*Encoding) MarshalYAML added in v0.7.0

func (e *Encoding) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the Encoding object.

func (*Encoding) Render added in v0.7.0

func (e *Encoding) Render() ([]byte, error)

Render will return a YAML representation of the Encoding object as a byte slice.

type Header 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"`
	AllowReserved   bool                                       `json:"allowReserved,omitempty" yaml:"allowReserved,omitempty"`
	Schema          *highbase.SchemaProxy                      `json:"schema,omitempty" yaml:"schema,omitempty"`
	Example         *yaml.Node                                 `json:"example,omitempty" yaml:"example,omitempty"`
	Examples        *orderedmap.Map[string, *highbase.Example] `json:"examples,omitempty" yaml:"examples,omitempty"`
	Content         *orderedmap.Map[string, *MediaType]        `json:"content,omitempty" yaml:"content,omitempty"`
	Extensions      *orderedmap.Map[string, *yaml.Node]        `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

Header represents a high-level OpenAPI 3+ Header object that is backed by a low-level one.

func NewHeader

func NewHeader(header *low.Header) *Header

NewHeader creates a new high-level Header instance from a low-level one.

func (*Header) GoLow

func (h *Header) GoLow() *low.Header

GoLow returns the low-level Header instance used to create the high-level one.

func (*Header) GoLowUntyped added in v0.7.0

func (h *Header) GoLowUntyped() any

GoLowUntyped will return the low-level Header instance that was used to create the high-level one, with no type

func (*Header) MarshalYAML added in v0.7.0

func (h *Header) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the Header object.

func (*Header) Render added in v0.7.0

func (h *Header) Render() ([]byte, error)

Render will return a YAML representation of the Header object as a byte slice.

type Link struct {
	OperationRef string                              `json:"operationRef,omitempty" yaml:"operationRef,omitempty"`
	OperationId  string                              `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	Parameters   *orderedmap.Map[string, string]     `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	RequestBody  string                              `json:"requestBody,omitempty" yaml:"requestBody,omitempty"`
	Description  string                              `json:"description,omitempty" yaml:"description,omitempty"`
	Server       *Server                             `json:"server,omitempty" yaml:"server,omitempty"`
	Extensions   *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

Link represents a high-level OpenAPI 3+ Link object that is backed by a low-level one.

The Link object represents a possible design-time link for a response. The presence of a link does not guarantee the caller’s ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.

Unlike dynamic links (i.e. links provided in the response payload), the OAS linking mechanism does not require link information in the runtime response.

For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation.

func NewLink(link *low.Link) *Link

NewLink will create a new high-level Link instance from a low-level one.

func (*Link) GoLow

func (l *Link) GoLow() *low.Link

GoLow will return the low-level Link instance used to create the high-level one.

func (*Link) GoLowUntyped added in v0.7.0

func (l *Link) GoLowUntyped() any

GoLowUntyped will return the low-level Link instance that was used to create the high-level one, with no type

func (*Link) MarshalYAML added in v0.7.0

func (l *Link) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the Link object.

func (*Link) Render added in v0.7.0

func (l *Link) Render() ([]byte, error)

Render will return a YAML representation of the Link object as a byte slice.

type MediaType

type MediaType struct {
	Schema     *base.SchemaProxy                      `json:"schema,omitempty" yaml:"schema,omitempty"`
	Example    *yaml.Node                             `json:"example,omitempty" yaml:"example,omitempty"`
	Examples   *orderedmap.Map[string, *base.Example] `json:"examples,omitempty" yaml:"examples,omitempty"`
	Encoding   *orderedmap.Map[string, *Encoding]     `json:"encoding,omitempty" yaml:"encoding,omitempty"`
	Extensions *orderedmap.Map[string, *yaml.Node]    `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

MediaType represents a high-level OpenAPI MediaType object that is backed by a low-level one.

Each Media Type Object provides schema and examples for the media type identified by its key.

func NewMediaType

func NewMediaType(mediaType *low.MediaType) *MediaType

NewMediaType will create a new high-level MediaType instance from a low-level one.

func (*MediaType) GoLow

func (m *MediaType) GoLow() *low.MediaType

GoLow will return the low-level instance of MediaType used to create the high-level one.

func (*MediaType) GoLowUntyped added in v0.7.0

func (m *MediaType) GoLowUntyped() any

GoLowUntyped will return the low-level MediaType instance that was used to create the high-level one, with no type

func (*MediaType) MarshalYAML added in v0.7.0

func (m *MediaType) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the MediaType object.

func (*MediaType) MarshalYAMLInline added in v0.8.4

func (m *MediaType) MarshalYAMLInline() (interface{}, error)

func (*MediaType) Render added in v0.7.0

func (m *MediaType) Render() ([]byte, error)

Render will return a YAML representation of the MediaType object as a byte slice.

func (*MediaType) RenderInline added in v0.8.4

func (m *MediaType) RenderInline() ([]byte, error)

type OAuthFlow

type OAuthFlow 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           *orderedmap.Map[string, string]     `json:"scopes,omitempty" yaml:"scopes,omitempty"`
	Extensions       *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

OAuthFlow represents a high-level OpenAPI 3+ OAuthFlow object that is backed by a low-level one.

func NewOAuthFlow

func NewOAuthFlow(flow *low.OAuthFlow) *OAuthFlow

NewOAuthFlow creates a new high-level OAuthFlow instance from a low-level one.

func (*OAuthFlow) GoLow

func (o *OAuthFlow) GoLow() *low.OAuthFlow

GoLow returns the low-level OAuthFlow instance used to create the high-level one.

func (*OAuthFlow) GoLowUntyped added in v0.7.0

func (o *OAuthFlow) GoLowUntyped() any

GoLowUntyped will return the low-level Discriminator instance that was used to create the high-level one, with no type

func (*OAuthFlow) MarshalYAML added in v0.7.0

func (o *OAuthFlow) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the OAuthFlow object.

func (*OAuthFlow) Render added in v0.7.0

func (o *OAuthFlow) Render() ([]byte, error)

Render will return a YAML representation of the OAuthFlow object as a byte slice.

type OAuthFlows

type OAuthFlows 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"`
	Extensions        *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

OAuthFlows represents a high-level OpenAPI 3+ OAuthFlows object that is backed by a low-level one.

func NewOAuthFlows

func NewOAuthFlows(flows *low.OAuthFlows) *OAuthFlows

NewOAuthFlows creates a new high-level OAuthFlows instance from a low-level one.

func (*OAuthFlows) GoLow

func (o *OAuthFlows) GoLow() *low.OAuthFlows

GoLow returns the low-level OAuthFlows instance used to create the high-level one.

func (*OAuthFlows) GoLowUntyped added in v0.7.0

func (o *OAuthFlows) GoLowUntyped() any

GoLowUntyped will return the low-level OAuthFlows instance that was used to create the high-level one, with no type

func (*OAuthFlows) MarshalYAML added in v0.7.0

func (o *OAuthFlows) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the OAuthFlows object.

func (*OAuthFlows) Render added in v0.7.0

func (o *OAuthFlows) Render() ([]byte, error)

Render will return a YAML representation of the OAuthFlows object as a byte slice.

type Operation

type Operation 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 *base.ExternalDoc                   `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	OperationId  string                              `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	Parameters   []*Parameter                        `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	RequestBody  *RequestBody                        `json:"requestBody,omitempty" yaml:"requestBody,omitempty"`
	Responses    *Responses                          `json:"responses,omitempty" yaml:"responses,omitempty"`
	Callbacks    *orderedmap.Map[string, *Callback]  `json:"callbacks,omitempty" yaml:"callbacks,omitempty"`
	Deprecated   *bool                               `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	Security     []*base.SecurityRequirement         `json:"security,omitempty" yaml:"security,omitempty"`
	Servers      []*Server                           `json:"servers,omitempty" yaml:"servers,omitempty"`
	Extensions   *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

Operation is a high-level representation of an OpenAPI 3+ Operation object, backed by a low-level one.

An Operation is perhaps the most important object of the entire specification. Everything of value happens here. The entire being for existence of this library and the specification, is this Operation.

func NewOperation

func NewOperation(operation *low.Operation) *Operation

NewOperation will create a new Operation instance from a low-level one.

func (*Operation) GoLow

func (o *Operation) GoLow() *low.Operation

GoLow will return the low-level Operation instance that was used to create the high-level one.

func (*Operation) GoLowUntyped added in v0.7.0

func (o *Operation) GoLowUntyped() any

GoLowUntyped will return the low-level Discriminator instance that was used to create the high-level one, with no type

func (*Operation) MarshalYAML added in v0.7.0

func (o *Operation) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the Operation object.

func (*Operation) MarshalYAMLInline added in v0.8.4

func (o *Operation) MarshalYAMLInline() (interface{}, error)

func (*Operation) Render added in v0.7.0

func (o *Operation) Render() ([]byte, error)

Render will return a YAML representation of the Operation object as a byte slice.

func (*Operation) RenderInline added in v0.8.4

func (o *Operation) RenderInline() ([]byte, error)

type Parameter

type Parameter 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,renderZero,omitempty" yaml:"required,renderZero,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,renderZero,omitempty" yaml:"explode,renderZero,omitempty"`
	AllowReserved   bool                                   `json:"allowReserved,omitempty" yaml:"allowReserved,omitempty"`
	Schema          *base.SchemaProxy                      `json:"schema,omitempty" yaml:"schema,omitempty"`
	Example         *yaml.Node                             `json:"example,omitempty" yaml:"example,omitempty"`
	Examples        *orderedmap.Map[string, *base.Example] `json:"examples,omitempty" yaml:"examples,omitempty"`
	Content         *orderedmap.Map[string, *MediaType]    `json:"content,omitempty" yaml:"content,omitempty"`
	Extensions      *orderedmap.Map[string, *yaml.Node]    `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

Parameter represents a high-level OpenAPI 3+ Parameter object, that is backed by a low-level one.

A unique parameter is defined by a combination of a name and location.

func NewParameter

func NewParameter(param *low.Parameter) *Parameter

NewParameter will create a new high-level instance of a Parameter, using a low-level one.

func (*Parameter) GoLow

func (p *Parameter) GoLow() *low.Parameter

GoLow returns the low-level Parameter used to create the high-level one.

func (*Parameter) GoLowUntyped added in v0.7.0

func (p *Parameter) GoLowUntyped() any

GoLowUntyped will return the low-level Discriminator instance that was used to create the high-level one, with no type

func (*Parameter) IsDefaultFormEncoding added in v0.8.0

func (p *Parameter) IsDefaultFormEncoding() bool

IsDefaultFormEncoding will return true if the parameter has no exploded value, or has exploded set to true, and no style or a style set to form. This combination is the default encoding/serialization style for parameters for OpenAPI 3+

func (*Parameter) IsDefaultHeaderEncoding added in v0.8.0

func (p *Parameter) IsDefaultHeaderEncoding() bool

IsDefaultHeaderEncoding will return true if the parameter has no exploded value, or has exploded set to false, and no style or a style set to simple. This combination is the default encoding/serialization style for header parameters for OpenAPI 3+

func (*Parameter) IsDefaultPathEncoding added in v0.8.0

func (p *Parameter) IsDefaultPathEncoding() bool

IsDefaultPathEncoding will return true if the parameter has no exploded value, or has exploded set to false, and no style or a style set to simple. This combination is the default encoding/serialization style for path parameters for OpenAPI 3+

func (*Parameter) IsExploded added in v0.8.0

func (p *Parameter) IsExploded() bool

IsExploded will return true if the parameter is exploded, false otherwise.

func (*Parameter) MarshalYAML added in v0.7.0

func (p *Parameter) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the Encoding object.

func (*Parameter) MarshalYAMLInline added in v0.8.4

func (p *Parameter) MarshalYAMLInline() (interface{}, error)

func (*Parameter) Render added in v0.7.0

func (p *Parameter) Render() ([]byte, error)

Render will return a YAML representation of the Encoding object as a byte slice.

func (*Parameter) RenderInline added in v0.8.4

func (p *Parameter) RenderInline() ([]byte, error)

type PathItem

type PathItem struct {
	Description string                              `json:"description,omitempty" yaml:"description,omitempty"`
	Summary     string                              `json:"summary,omitempty" yaml:"summary,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  []*Parameter                        `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	Extensions  *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

PathItem represents a high-level OpenAPI 3+ PathItem object backed by a low-level one.

Describes the operations available on a single path. A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.

func NewPathItem

func NewPathItem(pathItem *lowV3.PathItem) *PathItem

NewPathItem creates a new high-level PathItem instance from a low-level one.

func (*PathItem) GetOperations added in v0.2.7

func (p *PathItem) GetOperations() *orderedmap.Map[string, *Operation]

func (*PathItem) GoLow

func (p *PathItem) GoLow() *lowV3.PathItem

GoLow returns the low level instance of PathItem, used to build the high-level one.

func (*PathItem) GoLowUntyped added in v0.7.0

func (p *PathItem) GoLowUntyped() any

GoLowUntyped will return the low-level PathItem instance that was used to create the high-level one, with no type

func (*PathItem) MarshalYAML added in v0.7.0

func (p *PathItem) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the PathItem object.

func (*PathItem) MarshalYAMLInline added in v0.8.4

func (p *PathItem) MarshalYAMLInline() (interface{}, error)

func (*PathItem) Render added in v0.7.0

func (p *PathItem) Render() ([]byte, error)

Render will return a YAML representation of the PathItem object as a byte slice.

func (*PathItem) RenderInline added in v0.8.4

func (p *PathItem) RenderInline() ([]byte, error)

type Paths

type Paths struct {
	PathItems  *orderedmap.Map[string, *PathItem]  `json:"-" yaml:"-"`
	Extensions *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

Paths represents a high-level OpenAPI 3+ Paths object, that is backed by a low-level one.

Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the Server Object in order to construct the full URL. The Paths MAY be empty, due to Access Control List (ACL) constraints.

func NewPaths

func NewPaths(paths *v3low.Paths) *Paths

NewPaths creates a new high-level instance of Paths from a low-level one.

func (*Paths) GoLow

func (p *Paths) GoLow() *v3low.Paths

GoLow returns the low-level Paths instance used to create the high-level one.

func (*Paths) GoLowUntyped added in v0.7.0

func (p *Paths) GoLowUntyped() any

GoLowUntyped will return the low-level Paths instance that was used to create the high-level one, with no type

func (*Paths) MarshalYAML added in v0.7.0

func (p *Paths) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the Paths object.

func (*Paths) MarshalYAMLInline added in v0.8.4

func (p *Paths) MarshalYAMLInline() (interface{}, error)

func (*Paths) Render added in v0.7.0

func (p *Paths) Render() ([]byte, error)

Render will return a YAML representation of the Paths object as a byte slice.

func (*Paths) RenderInline added in v0.8.4

func (p *Paths) RenderInline() ([]byte, error)

type RequestBody

type RequestBody struct {
	Description string                              `json:"description,omitempty" yaml:"description,omitempty"`
	Content     *orderedmap.Map[string, *MediaType] `json:"content,omitempty" yaml:"content,omitempty"`
	Required    *bool                               `json:"required,omitempty" yaml:"required,renderZero,omitempty"`
	Extensions  *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

RequestBody represents a high-level OpenAPI 3+ RequestBody object, backed by a low-level one.

func NewRequestBody

func NewRequestBody(rb *low.RequestBody) *RequestBody

NewRequestBody will create a new high-level RequestBody instance, from a low-level one.

func (*RequestBody) GoLow

func (r *RequestBody) GoLow() *low.RequestBody

GoLow returns the low-level RequestBody instance used to create the high-level one.

func (*RequestBody) GoLowUntyped added in v0.7.0

func (r *RequestBody) GoLowUntyped() any

GoLowUntyped will return the low-level RequestBody instance that was used to create the high-level one, with no type

func (*RequestBody) MarshalYAML added in v0.7.0

func (r *RequestBody) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the RequestBody object.

func (*RequestBody) MarshalYAMLInline added in v0.8.4

func (r *RequestBody) MarshalYAMLInline() (interface{}, error)

func (*RequestBody) Render added in v0.7.0

func (r *RequestBody) Render() ([]byte, error)

Render will return a YAML representation of the RequestBody object as a byte slice.

func (*RequestBody) RenderInline added in v0.8.4

func (r *RequestBody) RenderInline() ([]byte, error)

type Response

type Response struct {
	Description string                              `json:"description,omitempty" yaml:"description,omitempty"`
	Headers     *orderedmap.Map[string, *Header]    `json:"headers,omitempty" yaml:"headers,omitempty"`
	Content     *orderedmap.Map[string, *MediaType] `json:"content,omitempty" yaml:"content,omitempty"`
	Links       *orderedmap.Map[string, *Link]      `json:"links,omitempty" yaml:"links,omitempty"`
	Extensions  *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

Response represents a high-level OpenAPI 3+ Response object that is backed by a low-level one.

Describes a single response from an API Operation, including design-time, static links to operations based on the response.

func NewResponse

func NewResponse(response *low.Response) *Response

NewResponse creates a new high-level Response object that is backed by a low-level one.

func (*Response) GoLow

func (r *Response) GoLow() *low.Response

GoLow returns the low-level Response object that was used to create the high-level one.

func (*Response) GoLowUntyped added in v0.7.0

func (r *Response) GoLowUntyped() any

GoLowUntyped will return the low-level Response instance that was used to create the high-level one, with no type

func (*Response) MarshalYAML added in v0.7.0

func (r *Response) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the Response object.

func (*Response) MarshalYAMLInline added in v0.8.4

func (r *Response) MarshalYAMLInline() (interface{}, error)

func (*Response) Render added in v0.7.0

func (r *Response) Render() ([]byte, error)

Render will return a YAML representation of the Response object as a byte slice.

func (*Response) RenderInline added in v0.8.4

func (r *Response) RenderInline() ([]byte, error)

type Responses

type Responses struct {
	Codes      *orderedmap.Map[string, *Response]  `json:"-" yaml:"-"`
	Default    *Response                           `json:"default,omitempty" yaml:"default,omitempty"`
	Extensions *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

Responses represents a high-level OpenAPI 3+ Responses object that is backed by a low-level one.

It's a container for the expected responses of an operation. The container maps a HTTP response code to the expected response.

The specification is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors.

The default MAY be used as a default response object for all HTTP codes that are not covered individually by the Responses Object.

The Responses Object MUST contain at least one response code, and if only one response code is provided it SHOULD be the response for a successful operation call.

func NewResponses

func NewResponses(responses *low.Responses) *Responses

NewResponses will create a new high-level Responses instance from a low-level one. It operates asynchronously internally, as each response may be considerable in complexity.

func (*Responses) FindResponseByCode

func (r *Responses) FindResponseByCode(code int) *Response

FindResponseByCode is a shortcut for looking up code by an integer vs. a string

func (*Responses) GoLow

func (r *Responses) GoLow() *low.Responses

GoLow returns the low-level Response object used to create the high-level one.

func (*Responses) GoLowUntyped added in v0.7.0

func (r *Responses) GoLowUntyped() any

GoLowUntyped will return the low-level Responses instance that was used to create the high-level one, with no type

func (*Responses) MarshalYAML added in v0.7.0

func (r *Responses) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the Responses object.

func (*Responses) MarshalYAMLInline added in v0.8.4

func (r *Responses) MarshalYAMLInline() (interface{}, error)

func (*Responses) Render added in v0.7.0

func (r *Responses) Render() ([]byte, error)

Render will return a YAML representation of the Responses object as a byte slice.

func (*Responses) RenderInline added in v0.8.4

func (r *Responses) RenderInline() ([]byte, error)

type SecurityScheme

type SecurityScheme 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"`
	Extensions       *orderedmap.Map[string, *yaml.Node] `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

SecurityScheme represents a high-level OpenAPI 3+ SecurityScheme object that is backed by a low-level one.

Defines a security scheme that can be used by the operations.

Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2’s common flows (implicit, password, client credentials and authorization code) as defined in RFC6749 (https://www.rfc-editor.org/rfc/rfc6749), and OpenID Connect Discovery. Please note that as of 2020, the implicit flow is about to be deprecated by OAuth 2.0 Security Best Current Practice. Recommended for most use case is Authorization Code Grant flow with PKCE.

func NewSecurityScheme

func NewSecurityScheme(ss *low.SecurityScheme) *SecurityScheme

NewSecurityScheme creates a new high-level SecurityScheme from a low-level one.

func (*SecurityScheme) GoLow

func (s *SecurityScheme) GoLow() *low.SecurityScheme

GoLow returns the low-level SecurityScheme that was used to create the high-level one.

func (*SecurityScheme) GoLowUntyped added in v0.7.0

func (s *SecurityScheme) GoLowUntyped() any

GoLowUntyped will return the low-level SecurityScheme instance that was used to create the high-level one, with no type

func (*SecurityScheme) MarshalYAML added in v0.7.0

func (s *SecurityScheme) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the Response object.

func (*SecurityScheme) Render added in v0.7.0

func (s *SecurityScheme) Render() ([]byte, error)

Render will return a YAML representation of the SecurityScheme object as a byte slice.

type Server

type Server struct {
	URL         string                                   `json:"url,omitempty" yaml:"url,omitempty"`
	Description string                                   `json:"description,omitempty" yaml:"description,omitempty"`
	Variables   *orderedmap.Map[string, *ServerVariable] `json:"variables,omitempty" yaml:"variables,omitempty"`
	Extensions  *orderedmap.Map[string, *yaml.Node]      `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

Server represents a high-level OpenAPI 3+ Server object, that is backed by a low level one.

func NewServer

func NewServer(server *low.Server) *Server

NewServer will create a new high-level Server instance from a low-level one.

func (*Server) GoLow

func (s *Server) GoLow() *low.Server

GoLow returns the low-level Server instance that was used to create the high-level one

func (*Server) GoLowUntyped added in v0.7.0

func (s *Server) GoLowUntyped() any

GoLowUntyped will return the low-level Server instance that was used to create the high-level one, with no type

func (*Server) MarshalYAML added in v0.7.0

func (s *Server) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the Server object.

func (*Server) Render added in v0.7.0

func (s *Server) Render() ([]byte, error)

Render will return a YAML representation of the Server object as a byte slice.

type ServerVariable

type ServerVariable struct {
	Enum        []string `json:"enum,omitempty" yaml:"enum,omitempty"`
	Default     string   `json:"default,omitempty" yaml:"default,omitempty"`
	Description string   `json:"description,omitempty" yaml:"description,omitempty"`
	// contains filtered or unexported fields
}

ServerVariable represents a high-level OpenAPI 3+ ServerVariable object, that is backed by a low-level one.

ServerVariable is an object representing a Server Variable for server URL template substitution. - https://spec.openapis.org/oas/v3.1.0#server-variable-object

func NewServerVariable

func NewServerVariable(variable *low.ServerVariable) *ServerVariable

NewServerVariable will return a new high-level instance of a ServerVariable from a low-level one.

func (*ServerVariable) GoLow

func (s *ServerVariable) GoLow() *low.ServerVariable

GoLow returns the low-level ServerVariable used to create the high\-level one.

func (*ServerVariable) GoLowUntyped added in v0.7.0

func (s *ServerVariable) GoLowUntyped() any

GoLowUntyped will return the low-level ServerVariable instance that was used to create the high-level one, with no type

func (*ServerVariable) MarshalYAML added in v0.7.0

func (s *ServerVariable) MarshalYAML() (interface{}, error)

MarshalYAML will create a ready to render YAML representation of the ServerVariable object.

func (*ServerVariable) Render added in v0.7.0

func (s *ServerVariable) Render() ([]byte, error)

Render will return a YAML representation of the ServerVariable object as a byte slice.

Jump to

Keyboard shortcuts

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