v3

package
v0.4.2 Latest Latest
Warning

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

 Go to latest Published: Dec 12, 2022 License: MIT Imports: 8 Imported by: 88

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, _ := ioutil.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.CreateDocument(info)

// Get upset if any errors were thrown.
if len(err) > 0 {
	for i := range err {
		fmt.Printf("error: %e", err[i])
	}
	panic("something went wrong")
}

// 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",
	len(doc.Paths.PathItems), 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 

func ExtractContent(elements map[lowmodel.KeyReference[string]]lowmodel.ValueReference[*low.MediaType]) map[string]*MediaType

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 

func ExtractEncoding(elements map[lowmodel.KeyReference[string]]lowmodel.ValueReference[*low.Encoding]) map[string]*Encoding

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

func ExtractHeaders 

func ExtractHeaders(elements map[lowmodel.KeyReference[string]]lowmodel.ValueReference[*low.Header]) map[string]*Header

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

Types

type Callback 

type Callback struct {
	Expression map[string]*PathItem
	Extensions map[string]any
	// 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.

type Components 

type Components struct {
	Schemas         map[string]*highbase.SchemaProxy
	Responses       map[string]*Response
	Parameters      map[string]*Parameter
	Examples        map[string]*highbase.Example
	RequestBodies   map[string]*RequestBody
	Headers         map[string]*Header
	SecuritySchemes map[string]*SecurityScheme
	Links           map[string]*Link
	Callbacks       map[string]*Callback
	Extensions      map[string]any
	// 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.

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

	// 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

	// 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 a url value of /.
	// - https://spec.openapis.org/oas/v3.1.0#server-object
	Servers []*Server

	// 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

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

	// 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

	// 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

	// 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

	// Extensions contains all custom extensions defined for the top-level document.
	Extensions map[string]any

	// 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

	// 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 map[string]*PathItem

	// 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
	// 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.

type Encoding 

type Encoding struct {
	ContentType   string
	Headers       map[string]*Header
	Style         string
	Explode       *bool
	AllowReserved bool
	// 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. 

type Header struct {
	Description     string
	Required        bool
	Deprecated      bool
	AllowEmptyValue bool
	Style           string
	Explode         bool
	AllowReserved   bool
	Schema          *highbase.SchemaProxy
	Example         any
	Examples        map[string]*highbase.Example
	Content         map[string]*MediaType
	Extensions      map[string]any
	// 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. 

type Link struct {
	OperationRef string
	OperationId  string
	Parameters   map[string]string
	RequestBody  string
	Description  string
	Server       *Server
	Extensions   map[string]any
	// 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.

type MediaType 

type MediaType struct {
	Schema     *base.SchemaProxy
	Example    any
	Examples   map[string]*base.Example
	Encoding   map[string]*Encoding
	Extensions map[string]any
	// 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.

type OAuthFlow 

type OAuthFlow struct {
	AuthorizationUrl string
	TokenUrl         string
	RefreshUrl       string
	Scopes           map[string]string
	Extensions       map[string]any
	// 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.

type OAuthFlows 

type OAuthFlows struct {
	Implicit          *OAuthFlow
	Password          *OAuthFlow
	ClientCredentials *OAuthFlow
	AuthorizationCode *OAuthFlow
	Extensions        map[string]any
	// 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.

type Operation 

type Operation struct {
	Tags         []string
	Summary      string
	Description  string
	ExternalDocs *base.ExternalDoc
	OperationId  string
	Parameters   []*Parameter
	RequestBody  *RequestBody
	Responses    *Responses
	Callbacks    map[string]*Callback
	Deprecated   *bool
	Security     []*base.SecurityRequirement
	Servers      []*Server
	Extensions   map[string]any
	// 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.

type Parameter 

type Parameter struct {
	Name            string
	In              string
	Description     string
	Required        bool
	Deprecated      bool
	AllowEmptyValue bool
	Style           string
	Explode         *bool
	AllowReserved   bool
	Schema          *base.SchemaProxy
	Example         any
	Examples        map[string]*base.Example
	Content         map[string]*MediaType
	Extensions      map[string]any
	// 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.

type PathItem 

type PathItem struct {
	Description string
	Summary     string
	Get         *Operation
	Put         *Operation
	Post        *Operation
	Delete      *Operation
	Options     *Operation
	Head        *Operation
	Patch       *Operation
	Trace       *Operation
	Servers     []*Server
	Parameters  []*Parameter
	Extensions  map[string]any
	// 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 *low.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() map[string]*Operation

func (*PathItem) GoLow 

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

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

type Paths 

type Paths struct {
	PathItems  map[string]*PathItem
	Extensions map[string]any
	// 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 *low.Paths) *Paths

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

func (*Paths) GoLow 

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

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

type RequestBody 

type RequestBody struct {
	Description string
	Content     map[string]*MediaType
	Required    bool
	Extensions  map[string]any
	// 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.

type Response 

type Response struct {
	Description string
	Headers     map[string]*Header
	Content     map[string]*MediaType
	Extensions  map[string]any
	Links       map[string]*Link
	// 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.

type Responses 

type Responses struct {
	Codes      map[string]*Response
	Default    *Response
	Extensions map[string]any
	// 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.

type SecurityScheme 

type SecurityScheme struct {
	Type             string
	Description      string
	Name             string
	In               string
	Scheme           string
	BearerFormat     string
	Flows            *OAuthFlows
	OpenIdConnectUrl string
	Extensions       map[string]any
	// 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.

type Server 

type Server struct {
	URL         string
	Description string
	Variables   map[string]*ServerVariable
	Extensions  map[string]any
	// 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

type ServerVariable 

type ServerVariable struct {
	Enum        []string
	Default     string
	Description string
	// 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 to create the high\-level one.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.