low

package
v0.9.4 Latest Latest
Warning

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

 Go to latest Published: Jul 18, 2023 License: MIT Imports: 10 Imported by: 10

Documentation

Overview

Package low contains a set of low-level models that represent OpenAPI 2 and 3 documents. These low-level models (plumbing) are used to create high-level models, and used when deep knowledge about the original data, positions, comments and the original node structures.

Low-level models are not designed to be easily navigated, every single property is either a NodeReference an KeyReference or a ValueReference. These references hold the raw value and key or value nodes that contain the original yaml.Node trees that make up the object.

Navigating maps that use a KeyReference as a key is tricky, because there is no easy way to provide a lookup. Convenience methods for lookup up properties in a low-level model have therefore been provided.

Index

Constants

View Source 
const (
	HASH = "%x"
)

Variables

This section is empty.

Functions

func AreEqual added in v0.1.4 

func AreEqual(l, r Hashable) bool

AreEqual returns true if two Hashable objects are equal or not.

func BuildModel 

func BuildModel(node *yaml.Node, model interface{}) error

BuildModel accepts a yaml.Node pointer and a model, which can be any struct. Using reflection, the model is analyzed and the names of all the properties are extracted from the model and subsequently looked up from within the yaml.Node.Content value.

BuildModel is non-recursive and will only build out a single layer of the node tree.

func BuildModelAsync 

func BuildModelAsync(n *yaml.Node, model interface{}, lwg *sync.WaitGroup, errors *[]error)

BuildModelAsync is a convenience function for calling BuildModel from a goroutine, requires a sync.WaitGroup

func ExtractExtensions 

func ExtractExtensions(root *yaml.Node) map[KeyReference[string]]ValueReference[any]

ExtractExtensions will extract any 'x-' prefixed key nodes from a root node into a map. Requirements have been pre-cast:

Maps 

map[string]interface{} for maps

Slices 

[]interface{}

int, float, bool, string 

int64, float64, bool, string

func ExtractMap added in v0.1.0 

func ExtractMap[PT Buildable[N], N any](
	label string,
	root *yaml.Node,
	idx *index.SpecIndex,
) (map[KeyReference[string]]ValueReference[PT], *yaml.Node, *yaml.Node, error)

ExtractMap will extract a map of KeyReference and ValueReference from a root yaml.Node. The 'label' is used to locate the node to be extracted from the root node supplied.

The second return value is the yaml.Node found for the 'label' and the third return value is the yaml.Node found for the value extracted from the label node.

func ExtractMapExtensions added in v0.8.3 

func ExtractMapExtensions[PT Buildable[N], N any](
	label string,
	root *yaml.Node,
	idx *index.SpecIndex,
	extensions bool,
) (map[KeyReference[string]]ValueReference[PT], *yaml.Node, *yaml.Node, error)

ExtractMapExtensions will extract a map of KeyReference and ValueReference from a root yaml.Node. The 'label' is used to locate the node to be extracted from the root node supplied. Supply a bit to decide if extensions should be included or not. required in some use cases.

The second return value is the yaml.Node found for the 'label' and the third return value is the yaml.Node found for the value extracted from the label node.

func ExtractMapNoLookup added in v0.1.0 

func ExtractMapNoLookup[PT Buildable[N], N any](
	root *yaml.Node,
	idx *index.SpecIndex,
) (map[KeyReference[string]]ValueReference[PT], error)

ExtractMapNoLookup will extract a map of KeyReference and ValueReference from a root yaml.Node. The 'NoLookup' part refers to the fact that there is no key supplied as part of the extraction, there is no lookup performed and the root yaml.Node pointer is used directly.

This is useful when the node to be extracted, is already known and does not require a search.

func ExtractMapNoLookupExtensions added in v0.8.3 

func ExtractMapNoLookupExtensions[PT Buildable[N], N any](
	root *yaml.Node,
	idx *index.SpecIndex,
	includeExtensions bool,
) (map[KeyReference[string]]ValueReference[PT], error)

ExtractMapNoLookupExtensions will extract a map of KeyReference and ValueReference from a root yaml.Node. The 'NoLookup' part refers to the fact that there is no key supplied as part of the extraction, there is no lookup performed and the root yaml.Node pointer is used directly. Pass a true bit to includeExtensions to include extension keys in the map.

This is useful when the node to be extracted, is already known and does not require a search.

func ExtractObjectRaw 

func ExtractObjectRaw[T Buildable[N], N any](root *yaml.Node, idx *index.SpecIndex) (T, error, bool, string)

ExtractObjectRaw will extract a typed Buildable[N] object from a root yaml.Node. The 'raw' aspect is that there is no NodeReference wrapper around the result returned, just the raw object.

func GenerateHashString added in v0.1.4 

func GenerateHashString(v any) string

GenerateHashString will generate a SHA36 hash of any object passed in. If the object is Hashable then the underlying Hash() method will be called.

func GetCircularReferenceResult 

func GetCircularReferenceResult(node *yaml.Node, idx *index.SpecIndex) *index.CircularReferenceResult

GetCircularReferenceResult will check if a node is part of a circular reference chain and then return that index.CircularReferenceResult it was located in. Returns nil if not found.

func HashToString added in v0.1.4 

func HashToString(hash [32]byte) string

func IsCircular 

func IsCircular(node *yaml.Node, idx *index.SpecIndex) bool

IsCircular will determine if the node in question, is part of a circular reference chain discovered by the index.

func LocateRefNode 

func LocateRefNode(root *yaml.Node, idx *index.SpecIndex) (*yaml.Node, error)

LocateRefNode will perform a complete lookup for a $ref node. This function searches the entire index for the reference being supplied. If there is a match found, the reference *yaml.Node is returned.

func SetField 

func SetField(field *reflect.Value, valueNode *yaml.Node, keyNode *yaml.Node) error

SetField accepts a field reflection value, a yaml.Node valueNode and a yaml.Node keyNode. Using reflection, the function will attempt to set the value of the field based on the key and value nodes. This method is only useful for low-level models, it has no value to high-level ones.

func SetReference added in v0.7.0 

func SetReference(obj any, ref string)

Types

type Buildable 

type Buildable[T any] interface {
	Build(node *yaml.Node, idx *index.SpecIndex) error
	*T
}

Buildable is an interface for any struct that can be 'built out'. This means that a struct can accept a root node and a reference to the index that carries data about any references used.

Used by generic functions when automatically building out structs based on yaml.Node inputs.

type HasDescription added in v0.2.0 

type HasDescription interface {
	GetDescription() *NodeReference[string]
}

type HasExtensions added in v0.1.4 

type HasExtensions[T any] interface {

	// GetExtensions returns generic low level extensions
	GetExtensions() map[KeyReference[string]]ValueReference[any]
}

HasExtensions is implemented by any object that exposes extensions

type HasExtensionsUntyped added in v0.7.0 

type HasExtensionsUntyped interface {

	// GetExtensions returns generic low level extensions
	GetExtensions() map[KeyReference[string]]ValueReference[any]
}

HasExtensionsUntyped is implemented by any object that exposes extensions

type HasExternalDocs added in v0.2.0 

type HasExternalDocs interface {
	GetExternalDocs() *NodeReference[any]
}

type HasInfo added in v0.2.0 

type HasInfo interface {
	GetInfo() *NodeReference[any]
}

type HasKeyNode added in v0.7.0 

type HasKeyNode interface {
	GetKeyNode() *yaml.Node
}

HasKeyNode is implemented by KeyReference to return the yaml.Node backing the key.

type HasValue added in v0.1.4 

type HasValue[T any] interface {
	GetValue() T
	GetValueNode() *yaml.Node
	IsEmpty() bool
	*T
}

HasValue is implemented by NodeReference and ValueReference to return the yaml.Node backing the value.

type HasValueNode added in v0.1.4 

type HasValueNode[T any] interface {
	GetValueNode() *yaml.Node
	*T
}

HasValueNode is implemented by NodeReference and ValueReference to return the yaml.Node backing the value.

type HasValueNodeUntyped added in v0.7.0 

type HasValueNodeUntyped interface {
	GetValueNode() *yaml.Node
	IsReferenced
}

HasValueNodeUntyped is implemented by NodeReference and ValueReference to return the yaml.Node backing the value.

type HasValueUnTyped added in v0.7.0 

type HasValueUnTyped interface {
	GetValueUntyped() any
	GetValueNode() *yaml.Node
}

HasValueUnTyped is implemented by NodeReference and ValueReference to return the yaml.Node backing the value.

type Hashable added in v0.1.4 

type Hashable interface {
	Hash() [32]byte
}

Hashable defines any struct that implements a Hash function that returns a 256SHA hash of the state of the representative object. Great for equality checking!

type IsReferenced added in v0.7.0 

type IsReferenced interface {
	IsReference() bool
	GetReference() string
	SetReference(string)
}

type KeyReference 

type KeyReference[T any] struct {

	// The value being referenced.
	Value T

	// The yaml.Node that holds this referenced key
	KeyNode *yaml.Node
}

KeyReference is a low-level container for key nodes holding a Value of type T. A KeyNode is a pointer to the yaml.Node that holds a key to a value.

func (KeyReference[T]) GenerateMapKey 

func (n KeyReference[T]) GenerateMapKey() string

GenerateMapKey will return a string based on the line and column number of the node, e.g. 33:56 for line 33, col 56.

func (KeyReference[T]) GetKeyNode added in v0.7.0 

func (n KeyReference[T]) GetKeyNode() *yaml.Node

GetKeyNode will return the yaml.Node containing the reference key node.

func (KeyReference[T]) GetValueUntyped added in v0.7.0 

func (n KeyReference[T]) GetValueUntyped() any

GetValueUntyped will return the raw value of the node with no type

func (KeyReference[T]) IsEmpty 

func (n KeyReference[T]) IsEmpty() bool

IsEmpty will return true if this reference has no key or value nodes assigned (it's been ignored)

type NodeReference 

type NodeReference[T any] struct {

	// The value being referenced
	Value T

	// The yaml.Node that holds the value
	ValueNode *yaml.Node

	// The yaml.Node that is the key, that contains the value.
	KeyNode *yaml.Node

	// Is this value actually a reference in the original tree?
	ReferenceNode bool

	// If HasReference is true, then Reference contains the original $ref value.
	Reference string
}

NodeReference is a low-level container for holding a Value of type T, as well as references to a key yaml.Node that points to the key node that contains the value node, and the value node that contains the actual value.

func ExtractExample 

func ExtractExample(expNode, expLabel *yaml.Node) NodeReference[any]

ExtractExample will extract a value supplied as an example into a NodeReference. Value can be anything. the node value is untyped, so casting will be required when trying to use it.

func ExtractObject 

func ExtractObject[T Buildable[N], N any](label string, root *yaml.Node, idx *index.SpecIndex) (NodeReference[T], error)

ExtractObject will extract a typed Buildable[N] object from a root yaml.Node. The result is wrapped in a NodeReference[T] that contains the key node found and value node found when looking up the reference.

func (NodeReference[T]) GenerateMapKey 

func (n NodeReference[T]) GenerateMapKey() string

GenerateMapKey will return a string based on the line and column number of the node, e.g. 33:56 for line 33, col 56.

func (NodeReference[T]) GetKeyNode added in v0.7.0 

func (n NodeReference[T]) GetKeyNode() *yaml.Node

GetKeyNode will return the yaml.Node containing the reference key node

func (NodeReference[T]) GetReference added in v0.7.0 

func (n NodeReference[T]) GetReference() string

func (NodeReference[T]) GetValue added in v0.1.4 

func (n NodeReference[T]) GetValue() T

GetValue will return the raw value of the node

func (NodeReference[T]) GetValueNode added in v0.1.4 

func (n NodeReference[T]) GetValueNode() *yaml.Node

GetValueNode will return the yaml.Node containing the reference value node

func (NodeReference[T]) GetValueUntyped added in v0.7.0 

func (n NodeReference[T]) GetValueUntyped() any

GetValueUntyped will return the raw value of the node with no type

func (NodeReference[T]) IsEmpty 

func (n NodeReference[T]) IsEmpty() bool

IsEmpty will return true if this reference has no key or value nodes assigned (it's been ignored)

func (NodeReference[T]) IsReference added in v0.3.3 

func (n NodeReference[T]) IsReference() bool

IsReference will return true if the key node contains a $ref key.

func (NodeReference[T]) Mutate added in v0.0.8 

func (n NodeReference[T]) Mutate(value T) NodeReference[T]

Mutate will set the reference value to what is supplied. This happens to both the Value and ValueNode, which means the root document is permanently mutated and changes will be reflected in any serialization of the root document.

func (NodeReference[T]) NodeLineNumber added in v0.7.0 

func (n NodeReference[T]) NodeLineNumber() int

func (NodeReference[T]) SetReference added in v0.7.0 

func (n NodeReference[T]) SetReference(ref string)

type OpenAPIHeader added in v0.2.0 

type OpenAPIHeader interface {
	HasDescription
	Hash() [32]byte
	GetDeprecated() *NodeReference[bool]
	GetStyle() *NodeReference[string]
	GetAllowReserved() *NodeReference[bool]
	GetExplode() *NodeReference[bool]
	GetExample() *NodeReference[any]
	GetRequired() *NodeReference[bool]
	GetAllowEmptyValue() *NodeReference[bool]
	GetSchema() *NodeReference[any]   // requires cast.
	GetExamples() *NodeReference[any] // requires cast.
	GetContent() *NodeReference[any]  // requires cast.
}

type OpenAPIOperations added in v0.2.0 

type OpenAPIOperations interface {
	SharedOperations
	GetCallbacks() NodeReference[map[KeyReference[string]]ValueReference[any]] // requires cast
	GetServers() NodeReference[any]                                            // requires cast.
}

type OpenAPIParameter added in v0.2.0 

type OpenAPIParameter interface {
	SharedParameters
	GetDeprecated() *NodeReference[bool]
	GetStyle() *NodeReference[string]
	GetAllowReserved() *NodeReference[bool]
	GetExplode() *NodeReference[bool]
	GetExample() *NodeReference[any]
	GetExamples() *NodeReference[any] // requires cast.
	GetContent() *NodeReference[any]  // requires cast.
}

type Reference added in v0.7.0 

type Reference struct {
	Reference string `json:"-" yaml:"-"`
}

func (*Reference) GetReference added in v0.7.0 

func (r *Reference) GetReference() string

func (*Reference) IsReference added in v0.7.0 

func (r *Reference) IsReference() bool

func (*Reference) SetReference added in v0.7.0 

func (r *Reference) SetReference(ref string)

type SharedOperations added in v0.2.0 

type SharedOperations interface {
	//HasDescription
	//HasExternalDocs
	GetOperationId() NodeReference[string]
	GetExternalDocs() NodeReference[any]
	GetDescription() NodeReference[string]
	GetTags() NodeReference[[]ValueReference[string]]
	GetSummary() NodeReference[string]
	GetDeprecated() NodeReference[bool]
	GetExtensions() map[KeyReference[string]]ValueReference[any]
	GetResponses() NodeReference[any]  // requires cast.
	GetParameters() NodeReference[any] // requires cast.
	GetSecurity() NodeReference[any]   // requires cast.
}

type SharedParameters added in v0.2.0 

type SharedParameters interface {
	HasDescription
	Hash() [32]byte
	GetName() *NodeReference[string]
	GetIn() *NodeReference[string]
	GetAllowEmptyValue() *NodeReference[bool]
	GetRequired() *NodeReference[bool]
	GetSchema() *NodeReference[any] // requires cast.
}

type SwaggerHeader added in v0.2.0 

type SwaggerHeader interface {
	HasDescription
	Hash() [32]byte
	GetType() *NodeReference[string]
	GetFormat() *NodeReference[string]
	GetCollectionFormat() *NodeReference[string]
	GetDefault() *NodeReference[any]
	GetMaximum() *NodeReference[int]
	GetExclusiveMaximum() *NodeReference[bool]
	GetMinimum() *NodeReference[int]
	GetExclusiveMinimum() *NodeReference[bool]
	GetMaxLength() *NodeReference[int]
	GetMinLength() *NodeReference[int]
	GetPattern() *NodeReference[string]
	GetMaxItems() *NodeReference[int]
	GetMinItems() *NodeReference[int]
	GetUniqueItems() *NodeReference[bool]
	GetEnum() *NodeReference[[]ValueReference[any]]
	GetMultipleOf() *NodeReference[int]
	GetItems() *NodeReference[any] // requires cast.
}

type SwaggerOperations added in v0.2.0 

type SwaggerOperations interface {
	SharedOperations
	GetConsumes() NodeReference[[]ValueReference[string]]
	GetProduces() NodeReference[[]ValueReference[string]]
	GetSchemes() NodeReference[[]ValueReference[string]]
}

type SwaggerParameter added in v0.2.0 

type SwaggerParameter interface {
	SharedParameters
	GetType() *NodeReference[string]
	GetFormat() *NodeReference[string]
	GetCollectionFormat() *NodeReference[string]
	GetDefault() *NodeReference[any]
	GetMaximum() *NodeReference[int]
	GetExclusiveMaximum() *NodeReference[bool]
	GetMinimum() *NodeReference[int]
	GetExclusiveMinimum() *NodeReference[bool]
	GetMaxLength() *NodeReference[int]
	GetMinLength() *NodeReference[int]
	GetPattern() *NodeReference[string]
	GetMaxItems() *NodeReference[int]
	GetMinItems() *NodeReference[int]
	GetUniqueItems() *NodeReference[bool]
	GetEnum() *NodeReference[[]ValueReference[any]]
	GetMultipleOf() *NodeReference[int]
}

type ValueReference 

type ValueReference[T any] struct {

	// The value being referenced.
	Value T

	// The yaml.Node that holds the referenced value
	ValueNode *yaml.Node

	// Is this value actually a reference in the original tree?
	ReferenceNode bool

	// If HasReference is true, then Reference contains the original $ref value.
	Reference string
}

ValueReference is a low-level container for value nodes that hold a Value of type T. A ValueNode is a pointer to the yaml.Node that holds the value.

func ExtractArray 

func ExtractArray[T Buildable[N], N any](label string, root *yaml.Node, idx *index.SpecIndex) ([]ValueReference[T],
	*yaml.Node, *yaml.Node, error,
)

ExtractArray will extract a slice of []ValueReference[T] from a root yaml.Node that is defined as a sequence. Used when the value being extracted is an array.

func FindItemInMap 

func FindItemInMap[T any](item string, collection map[KeyReference[string]]ValueReference[T]) *ValueReference[T]

FindItemInMap accepts a string key and a collection of KeyReference[string] and ValueReference[T]. Every KeyReference will have its value checked against the string key and if there is a match, it will be returned.

func (ValueReference[T]) GenerateMapKey 

func (n ValueReference[T]) GenerateMapKey() string

GenerateMapKey will return a string based on the line and column number of the node, e.g. 33:56 for line 33, col 56.

func (ValueReference[T]) GetReference added in v0.7.0 

func (n ValueReference[T]) GetReference() string

func (ValueReference[T]) GetValue added in v0.1.4 

func (n ValueReference[T]) GetValue() T

GetValue will return the raw value of the node

func (ValueReference[T]) GetValueNode added in v0.1.4 

func (n ValueReference[T]) GetValueNode() *yaml.Node

GetValueNode will return the yaml.Node containing the reference value node

func (ValueReference[T]) GetValueUntyped added in v0.7.0 

func (n ValueReference[T]) GetValueUntyped() any

GetValueUntyped will return the raw value of the node with no type

func (ValueReference[T]) IsEmpty 

func (n ValueReference[T]) IsEmpty() bool

IsEmpty will return true if this reference has no key or value nodes assigned (it's been ignored)

func (ValueReference[T]) IsReference added in v0.3.3 

func (n ValueReference[T]) IsReference() bool

IsReference will return true if the key node contains a $ref

func (ValueReference[T]) MarshalYAML added in v0.7.0 

func (n ValueReference[T]) MarshalYAML() (interface{}, error)

func (ValueReference[T]) Mutate added in v0.0.8 

func (n ValueReference[T]) Mutate(value T) ValueReference[T]

Mutate will set the reference value to what is supplied. This happens to both the Value and ValueNode, which means the root document is permanently mutated and changes will be reflected in any serialization of the root document.

func (ValueReference[T]) NodeLineNumber added in v0.7.0 

func (n ValueReference[T]) NodeLineNumber() int

NodeLineNumber will return the line number of the value node (or 0 if the value node is empty)

func (ValueReference[T]) SetReference added in v0.7.0 

func (n ValueReference[T]) SetReference(ref string)

Source Files

View all Source files

Directories

Path Synopsis
Package base contains shared low-level models that are used between both versions 2 and 3 of OpenAPI.
 Package base contains shared low-level models that are used between both versions 2 and 3 of OpenAPI.
Package v2 represents all Swagger / OpenAPI 2 low-level models.
 Package v2 represents all Swagger / OpenAPI 2 low-level models.
Package v3 represents all OpenAPI 3+ low-level models.
 Package v3 represents all OpenAPI 3+ low-level models.

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.