v2

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: 11 Imported by: 12

Documentation

Overview

Package v2 represents all Swagger / OpenAPI 2 high-level models. High-level models are easy to navigate and simple to extract what ever is required from a 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.

IMPORTANT: As a general rule, Swagger / OpenAPI 2 should be avoided for new projects.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Definitions

type Definitions struct {
	Definitions *orderedmap.Map[string, *highbase.SchemaProxy]
	// contains filtered or unexported fields
}

Definitions is a high-level represents of a Swagger / OpenAPI 2 Definitions object, backed by a low-level one.

An object to hold data types that can be consumed and produced by operations. These data types can be primitives, arrays or models.

func NewDefinitions

func NewDefinitions(definitions *low.Definitions) *Definitions

NewDefinitions will create a new high-level instance of a Definition from a low-level one.

func (*Definitions) GoLow

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

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

type Example added in v0.0.10

type Example struct {
	Values *orderedmap.Map[string, *yaml.Node]
	// contains filtered or unexported fields
}

Example represents a high-level Swagger / OpenAPI 2 Example object, backed by a low level one. Allows sharing examples for operation responses

func NewExample added in v0.0.10

func NewExample(examples *low.Examples) *Example

NewExample creates a new high-level Example instance from a low-level one.

func (*Example) GoLow added in v0.0.10

func (e *Example) GoLow() *low.Examples

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

type Header struct {
	Type             string
	Format           string
	Description      string
	Items            *Items
	CollectionFormat string
	Default          any
	Maximum          int
	ExclusiveMaximum bool
	Minimum          int
	ExclusiveMinimum bool
	MaxLength        int
	MinLength        int
	Pattern          string
	MaxItems         int
	MinItems         int
	UniqueItems      bool
	Enum             []any
	MultipleOf       int
	Extensions       *orderedmap.Map[string, *yaml.Node]
	// contains filtered or unexported fields
}

Header Represents a high-level Swagger / OpenAPI 2 Header object, backed by a low-level one. A Header is essentially identical to a Parameter, except it does not contain 'name' or 'in' properties.

func NewHeader

func NewHeader(header *low.Header) *Header

NewHeader will create a new high-level Swagger / OpenAPI 2 Header instance, from a low-level one.

func (*Header) GoLow

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

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

type Items

type Items struct {
	Type             string
	Format           string
	CollectionFormat string
	Items            *Items
	Default          *yaml.Node
	Maximum          int
	ExclusiveMaximum bool
	Minimum          int
	ExclusiveMinimum bool
	MaxLength        int
	MinLength        int
	Pattern          string
	MaxItems         int
	MinItems         int
	UniqueItems      bool
	Enum             []*yaml.Node
	MultipleOf       int
	// contains filtered or unexported fields
}

Items is a high-level representation of a Swagger / OpenAPI 2 Items object, backed by a low level one. Items is a limited subset of JSON-Schema's items object. It is used by parameter definitions that are not located in "body"

func NewItems

func NewItems(items *low.Items) *Items

NewItems creates a new high-level Items instance from a low-level one.

func (*Items) GoLow

func (i *Items) GoLow() *low.Items

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

type Operation

type Operation struct {
	Tags         []string
	Summary      string
	Description  string
	ExternalDocs *base.ExternalDoc
	OperationId  string
	Consumes     []string
	Produces     []string
	Parameters   []*Parameter
	Responses    *Responses
	Schemes      []string
	Deprecated   bool
	Security     []*base.SecurityRequirement
	Extensions   *orderedmap.Map[string, *yaml.Node]
	// contains filtered or unexported fields
}

Operation represents a high-level Swagger / OpenAPI 2 Operation object, backed by a low-level one. It describes a single API operation on a path.

func NewOperation

func NewOperation(operation *low.Operation) *Operation

NewOperation creates a new high-level Operation instance from a low-level one.

func (*Operation) GoLow

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

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

type Parameter

type Parameter struct {
	Name             string
	In               string
	Type             string
	Format           string
	Description      string
	Required         *bool
	AllowEmptyValue  *bool
	Schema           *base.SchemaProxy
	Items            *Items
	CollectionFormat string
	Default          *yaml.Node
	Maximum          *int
	ExclusiveMaximum *bool
	Minimum          *int
	ExclusiveMinimum *bool
	MaxLength        *int
	MinLength        *int
	Pattern          string
	MaxItems         *int
	MinItems         *int
	UniqueItems      *bool
	Enum             []*yaml.Node
	MultipleOf       *int
	Extensions       *orderedmap.Map[string, *yaml.Node]
	// contains filtered or unexported fields
}

Parameter represents a high-level Swagger / OpenAPI 2 Parameter object, backed by a low-level one.

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

There are five possible parameter types.

Path

Used together with Path Templating, where the parameter value is actually part of the operation's URL.
This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.

Query

Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.

Header

Custom headers that are expected as part of the request.

Body

The payload that's appended to the HTTP request. Since there can only be one payload, there can only be one body parameter.
The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only.
Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation.

Form

Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded, multipart/form-data
or both are used as the content type of the request (in Swagger's definition, the consumes property of an operation).
This is the only parameter type that can be used to send files, thus supporting the file type. Since form parameters
are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form
parameters have a different format based on the content-type used (for further details,
consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
  application/x-www-form-urlencoded - Similar to the format of Query parameters but as a payload. For example,
  foo=1&bar=swagger - both foo and bar are form parameters. This is normally used for simple parameters that are
                      being transferred.
  multipart/form-data - each parameter takes a section in the payload with an internal header. For example, for
                        the header Content-Disposition: form-data; name="submit-name" the name of the parameter is
                        submit-name. This type of form parameters is more commonly used for file transfers

https://swagger.io/specification/v2/#parameterObject

func NewParameter

func NewParameter(parameter *low.Parameter) *Parameter

NewParameter creates a new high-level instance of a Parameter from 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 ParameterDefinitions

type ParameterDefinitions struct {
	Definitions *orderedmap.Map[string, *Parameter]
	// contains filtered or unexported fields
}

ParameterDefinitions is a high-level representation of a Swagger / OpenAPI 2 Parameters Definitions object that is backed by a low-level one.

ParameterDefinitions holds parameters to be reused across operations. Parameter definitions can be referenced to the ones defined here. It does not define global operation parameters

func NewParametersDefinitions

func NewParametersDefinitions(parametersDefinitions *low.ParameterDefinitions) *ParameterDefinitions

NewParametersDefinitions creates a new instance of a high-level ParameterDefinitions, from a low-level one. Every parameter is extracted asynchronously due to the potential depth

func (*ParameterDefinitions) GoLow

GoLow returns the low-level ParameterDefinitions instance that backs the low-level one.

type PathItem

type PathItem struct {
	Ref        string
	Get        *Operation
	Put        *Operation
	Post       *Operation
	Delete     *Operation
	Options    *Operation
	Head       *Operation
	Patch      *Operation
	Parameters []*Parameter
	Extensions *orderedmap.Map[string, *yaml.Node]
	// contains filtered or unexported fields
}

PathItem represents a high-level Swagger / OpenAPI 2 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 tooling, but will not know which operations and parameters are available.

func NewPathItem

func NewPathItem(pathItem *lowV2.PathItem) *PathItem

NewPathItem will create a new high-level PathItem from a low-level one. All paths are built out asynchronously.

func (*PathItem) GetOperations added in v0.2.7

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

func (*PathItem) GoLow

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

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

type Paths

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

Paths represents a high-level Swagger / OpenAPI Paths object, backed by a low-level one.

func NewPaths

func NewPaths(paths *v2low.Paths) *Paths

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

func (*Paths) GoLow

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

GoLow returns the low-level Paths instance that backs the high level one.

type Response

type Response struct {
	Description string
	Schema      *base.SchemaProxy
	Headers     *orderedmap.Map[string, *Header]
	Examples    *Example
	Extensions  *orderedmap.Map[string, *yaml.Node]
	// contains filtered or unexported fields
}

Response is a representation of a high-level Swagger / OpenAPI 2 Response object, backed by a low-level one. Response describes a single response from an API Operation

func NewResponse

func NewResponse(response *low.Response) *Response

NewResponse creates a new high-level instance of Response from a low level one.

func (*Response) GoLow

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

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

type Responses

type Responses struct {
	Codes      *orderedmap.Map[string, *Response]
	Default    *Response
	Extensions *orderedmap.Map[string, *yaml.Node]
	// contains filtered or unexported fields
}

Responses is a high-level representation of a Swagger / OpenAPI 2 Responses object, backed by a low level one.

func NewResponses

func NewResponses(responses *low.Responses) *Responses

NewResponses will create a new high-level instance of Responses from a low-level one.

func (*Responses) GoLow

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

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

type ResponsesDefinitions

type ResponsesDefinitions struct {
	Definitions *orderedmap.Map[string, *Response]
	// contains filtered or unexported fields
}

ResponsesDefinitions is a high-level representation of a Swagger / OpenAPI 2 Responses Definitions object. that is backed by a low-level one.

ResponsesDefinitions is an object to hold responses to be reused across operations. Response definitions can be referenced to the ones defined here. It does not define global operation responses

func NewResponsesDefinitions

func NewResponsesDefinitions(responsesDefinitions *low.ResponsesDefinitions) *ResponsesDefinitions

NewResponsesDefinitions will create a new high-level instance of ResponsesDefinitions from a low-level one.

func (*ResponsesDefinitions) GoLow

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

type Scopes

type Scopes struct {
	Values *orderedmap.Map[string, string]
	// contains filtered or unexported fields
}

Scopes is a high-level representation of a Swagger / OpenAPI 2 OAuth2 Scopes object, that is backed by a low-level one.

Scopes lists the available scopes for an OAuth2 security scheme.

func NewScopes

func NewScopes(scopes *low.Scopes) *Scopes

NewScopes creates a new high-level instance of Scopes from a low-level one.

func (*Scopes) GoLow

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

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

type SecurityDefinitions

type SecurityDefinitions struct {
	Definitions *orderedmap.Map[string, *SecurityScheme]
	// contains filtered or unexported fields
}

SecurityDefinitions is a high-level representation of a Swagger / OpenAPI 2 Security Definitions object, that is backed by a low-level one.

A declaration of the security schemes available to be used in the specification. This does not enforce the security schemes on the operations and only serves to provide the relevant details for each scheme

func NewSecurityDefinitions

func NewSecurityDefinitions(definitions *low.SecurityDefinitions) *SecurityDefinitions

NewSecurityDefinitions creates a new high-level instance of a SecurityDefinitions from a low-level one.

func (*SecurityDefinitions) GoLow

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

type SecurityScheme

type SecurityScheme struct {
	Type             string
	Description      string
	Name             string
	In               string
	Flow             string
	AuthorizationUrl string
	TokenUrl         string
	Scopes           *Scopes
	Extensions       *orderedmap.Map[string, *yaml.Node]
	// contains filtered or unexported fields
}

SecurityScheme is a high-level representation of a Swagger / OpenAPI 2 SecurityScheme object backed by a low-level one.

SecurityScheme allows the definition of a security scheme that can be used by the operations. Supported schemes are basic authentication, an API key (either as a header or as a query parameter) and OAuth2's common flows (implicit, password, application and access code)

func NewSecurityScheme

func NewSecurityScheme(securityScheme *low.SecurityScheme) *SecurityScheme

NewSecurityScheme creates a new instance of 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 Swagger

type Swagger struct {
	// Swagger is the version of Swagger / OpenAPI being used, extracted from the 'swagger: 2.x' definition.
	Swagger string

	// Info represents a specification Info definition.
	// Provides metadata about the API. The metadata can be used by the clients if needed.
	// - https://swagger.io/specification/v2/#infoObject
	Info *base.Info

	// Host is The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor
	// sub-paths. It MAY include a port. If the host is not included, the host serving the documentation is to be used
	// (including the port). The host does not support path templating.
	Host string

	// BasePath is The base path on which the API is served, which is relative to the host. If it is not included, the API is
	// served directly under the host. The value MUST start with a leading slash (/).
	// The basePath does not support path templating.
	BasePath string

	// Schemes represents the transfer protocol of the API. Requirements MUST be from the list: "http", "https", "ws", "wss".
	// If the schemes is not included, the default scheme to be used is the one used to access
	// the Swagger definition itself.
	Schemes []string

	// Consumes is a list of MIME types the APIs can consume. This is global to all APIs but can be overridden on
	// specific API calls. Value MUST be as described under Mime Types.
	Consumes []string

	// Produces is a list of MIME types the APIs can produce. This is global to all APIs but can be overridden on
	// specific API calls. Value MUST be as described under Mime Types.
	Produces []string

	// Paths are the paths and operations for the API. Perhaps the most important part of the specification.
	//  - https://swagger.io/specification/v2/#pathsObject
	Paths *Paths

	// Definitions is an object to hold data types produced and consumed by operations. It's composed of Schema instances
	//  - https://swagger.io/specification/v2/#definitionsObject
	Definitions *Definitions

	// Parameters is an object to hold parameters that can be used across operations.
	// This property does not define global parameters for all operations.
	//  - https://swagger.io/specification/v2/#parametersDefinitionsObject
	Parameters *ParameterDefinitions

	// Responses is an object to hold responses that can be used across operations.
	// This property does not define global responses for all operations.
	//  - https://swagger.io/specification/v2/#responsesDefinitionsObject
	Responses *ResponsesDefinitions

	// SecurityDefinitions represents security scheme definitions that can be used across the specification.
	//  - https://swagger.io/specification/v2/#securityDefinitionsObject
	SecurityDefinitions *SecurityDefinitions

	// Security is a declaration of which security schemes are applied for the API as a whole. The list of values
	// describes alternative security schemes that can be used (that is, there is a logical OR between the security
	// requirements). Individual operations can override this definition.
	//  - https://swagger.io/specification/v2/#securityRequirementObject
	Security []*base.SecurityRequirement

	// Tags are A list of tags used by the specification 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://swagger.io/specification/v2/#tagObject
	Tags []*base.Tag

	// ExternalDocs is an instance of base.ExternalDoc for.. well, obvious really, innit.
	ExternalDocs *base.ExternalDoc

	// Extensions contains all custom extensions defined for the top-level document.
	Extensions *orderedmap.Map[string, *yaml.Node]
	// contains filtered or unexported fields
}

Swagger represents a high-level Swagger / OpenAPI 2 document. An instance of Swagger is the root of the specification.

func NewSwaggerDocument

func NewSwaggerDocument(document *low.Swagger) *Swagger

NewSwaggerDocument will create a new high-level Swagger document from a low-level one.

func (*Swagger) GoLow

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

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

Jump to

Keyboard shortcuts

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