low

package
v0.16.2 Latest Latest
Warning

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

 Go to latest Published: Jun 10, 2024 License: MIT Imports: 15 Imported by: 0

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 

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) *orderedmap.Map[KeyReference[string], ValueReference[*yaml.Node]]

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

Maps 

*orderedmap.Map[string, *yaml.Node] for maps

Slices 

[]interface{}

int, float, bool, string 

int64, float64, bool, string

func ExtractMap 

func ExtractMap[PT Buildable[N], N any](
	ctx context.Context,
	label string,
	root *yaml.Node,
	idx *index.SpecIndex,
) (*orderedmap.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 

func ExtractMapExtensions[PT Buildable[N], N any](
	ctx context.Context,
	label string,
	root *yaml.Node,
	idx *index.SpecIndex,
	extensions bool,
) (*orderedmap.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 

func ExtractMapNoLookup[PT Buildable[N], N any](
	ctx context.Context,
	root *yaml.Node,
	idx *index.SpecIndex,
) (*orderedmap.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 

func ExtractMapNoLookupExtensions[PT Buildable[N], N any](
	ctx context.Context,
	root *yaml.Node,
	idx *index.SpecIndex,
	includeExtensions bool,
) (*orderedmap.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](ctx context.Context, key, 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 FindItemInOrderedMapWithKey 

func FindItemInOrderedMapWithKey[T any](item string, collection *orderedmap.Map[KeyReference[string], ValueReference[T]]) (*KeyReference[string], *ValueReference[T])

FindItemInOrderedMapWithKey is the same as FindItemInOrderedMap, except this code returns the key as well as the value.

func GenerateHashString 

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 HashExtensions 

func HashExtensions(ext *orderedmap.Map[KeyReference[string], ValueReference[*yaml.Node]]) []string

HashExtensions will generate a hash from the low representation of extensions.

func HashToString 

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 LocateRefEnd 

func LocateRefEnd(ctx context.Context, root *yaml.Node, idx *index.SpecIndex, depth int) (*yaml.Node, *index.SpecIndex, error, context.Context)

LocateRefEnd 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. the function operates recursively and will keep iterating through references until it finds a non-reference node.

func LocateRefNode 

func LocateRefNode(root *yaml.Node, idx *index.SpecIndex) (*yaml.Node, *index.SpecIndex, 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 LocateRefNodeWithContext 

func LocateRefNodeWithContext(ctx context.Context, root *yaml.Node, idx *index.SpecIndex) (*yaml.Node, *index.SpecIndex, error, context.Context)

func SetField 

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

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 

func SetReference(obj any, ref string, refNode *yaml.Node)

func ValueToString 

func ValueToString(v any) string

Types

type Buildable 

type Buildable[T any] interface {
	Build(ctx context.Context, key, value *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 

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

type HasExtensions 

type HasExtensions[T any] interface {
	// GetExtensions returns generic low level extensions
	GetExtensions() *orderedmap.Map[KeyReference[string], ValueReference[*yaml.Node]]
}

HasExtensions is implemented by any object that exposes extensions

type HasExtensionsUntyped 

type HasExtensionsUntyped interface {
	// GetExtensions returns generic low level extensions
	GetExtensions() *orderedmap.Map[KeyReference[string], ValueReference[*yaml.Node]]
}

HasExtensionsUntyped is implemented by any object that exposes extensions

type HasExternalDocs 

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

type HasInfo 

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

type HasKeyNode 

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

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

type HasValue 

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 

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 

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

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

type HasValueUnTyped 

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 

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 

type IsReferenced interface {
	IsReference() bool
	GetReference() string
	GetReferenceNode() *yaml.Node
}

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 

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

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

func (KeyReference[T]) GetValueUntyped 

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)

func (KeyReference[T]) MarshalYAML 

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

type NodeReference 

type NodeReference[T any] struct {
	Reference

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

	Context context.Context
}

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 ExtractObject 

func ExtractObject[T Buildable[N], N any](ctx context.Context, 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 

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

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

func (NodeReference[T]) GetValue 

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

GetValue will return the raw value of the node

func (NodeReference[T]) GetValueNode 

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

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

func (NodeReference[T]) GetValueUntyped 

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]) Mutate 

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 

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

type OpenAPIHeader 

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

type OpenAPIOperations 

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

type OpenAPIParameter 

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

type Reference 

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

func (Reference) GetReference 

func (r Reference) GetReference() string

func (Reference) GetReferenceNode 

func (r Reference) GetReferenceNode() *yaml.Node

func (Reference) IsReference 

func (r Reference) IsReference() bool

func (*Reference) SetReference 

func (r *Reference) SetReference(ref string, node *yaml.Node)

type SetReferencer 

type SetReferencer interface {
	SetReference(ref string, node *yaml.Node)
}

type SharedOperations 

type SharedOperations interface {
	GetOperationId() NodeReference[string]
	GetExternalDocs() NodeReference[any]
	GetDescription() NodeReference[string]
	GetTags() NodeReference[[]ValueReference[string]]
	GetSummary() NodeReference[string]
	GetDeprecated() NodeReference[bool]
	GetExtensions() *orderedmap.Map[KeyReference[string], ValueReference[*yaml.Node]]
	GetResponses() NodeReference[any]  // requires cast.
	GetParameters() NodeReference[any] // requires cast.
	GetSecurity() NodeReference[any]   // requires cast.
}

TODO: this needs to be fixed, move returns to pointers.

type SharedParameters 

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 

type SwaggerHeader interface {
	HasDescription
	Hash() [32]byte
	GetType() *NodeReference[string]
	GetFormat() *NodeReference[string]
	GetCollectionFormat() *NodeReference[string]
	GetDefault() *NodeReference[*yaml.Node]
	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[*yaml.Node]]
	GetMultipleOf() *NodeReference[int]
	GetItems() *NodeReference[any] // requires cast.
}

type SwaggerOperations 

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

type SwaggerParameter 

type SwaggerParameter interface {
	SharedParameters
	GetType() *NodeReference[string]
	GetFormat() *NodeReference[string]
	GetCollectionFormat() *NodeReference[string]
	GetDefault() *NodeReference[*yaml.Node]
	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[*yaml.Node]]
	GetMultipleOf() *NodeReference[int]
}

type ValueReference 

type ValueReference[T any] struct {
	Reference

	// The value being referenced.
	Value T

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

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](ctx context.Context, 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 FindItemInOrderedMap 

func FindItemInOrderedMap[T any](item string, collection *orderedmap.Map[KeyReference[string], ValueReference[T]]) *ValueReference[T]

FindItemInOrderedMap 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]) GetValue 

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

GetValue will return the raw value of the node

func (ValueReference[T]) GetValueNode 

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

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

func (ValueReference[T]) GetValueUntyped 

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]) MarshalYAML 

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

func (ValueReference[T]) Mutate 

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 

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

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

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.