high

Documentation

Overview

Package high contains a set of high-level models that represent OpenAPI 2 and 3 documents. These high-level models (porcelain) are used by applications directly, rather than the low-level models plumbing) that are used to compose high level models.

High level models are simple to navigate, strongly typed, precise representations of the OpenAPI schema that are created from an OpenAPI specification.

All high level objects contains a 'GoLow' method. This 'GoLow' method will return the low-level model that was used to create it, which provides an engineer as much low level detail about the raw spec used to create those models, things like key/value breakdown of each value, lines, column, source comments etc.

Index

• func ExtractExtensions(extensions map[low.KeyReference[string]]low.ValueReference[any]) map[string]any
• func UnpackExtensions[T any, R low.HasExtensions[T]](low GoesLow[R]) (map[string]*T, error)
• type GoesLow
• type GoesLowUntyped
• type NodeBuilder
  • func NewNodeBuilder(high any, low any) *NodeBuilder
  • func (n *NodeBuilder) AddYAMLNode(parent *yaml.Node, entry *NodeEntry) *yaml.Node
  • func (n *NodeBuilder) Render() *yaml.Node
• type NodeEntry
• type Renderable
• type RenderableInline

Functions

func ExtractExtensions

func ExtractExtensions(extensions map[low.KeyReference[string]]low.ValueReference[any]) map[string]any

ExtractExtensions is a convenience method for converting low-level extension definitions, to a high level map[string]any definition that is easier to consume in applications.

func UnpackExtensions

func UnpackExtensions[T any, R low.HasExtensions[T]](low GoesLow[R]) (map[string]*T, error)

UnpackExtensions is a convenience function that makes it easy and simple to unpack an objects extensions into a complex type, provided as a generic. This function is for high-level models that implement `GoesLow()` and for low-level models that support extensions via `HasExtensions`.

This feature will be upgraded at some point to hold a registry of types and extension mappings to make this functionality available a little more automatically. You can read more about the discussion here: https://github.com/pb33f/libopenapi/issues/8

`T` represents the Type you want to unpack into `R` represents the LOW type of the object that contains the extensions (not the high) `low` represents the HIGH type of the object that contains the extensions.

to use:

schema := schemaProxy.Schema() // any high-level object that has
extensions, err := UnpackExtensions[MyComplexType, low.Schema](schema)

Types

type GoesLow

type GoesLow[T any] interface {

	// GoLow returns the low-level object that was used to create the high-level object. This allows consumers
	// to dive-down into the plumbing API at any point in the model.
	GoLow() T
}

GoesLow is used to represent any high-level model. All high level models meet this interface and can be used to extract low-level models from any high-level model.

type GoesLowUntyped

type GoesLowUntyped interface {

	// GoLowUntyped returns the low-level object that was used to create the high-level object. This allows consumers
	// to dive-down into the plumbing API at any point in the model.
	GoLowUntyped() any
}

GoesLowUntyped is used to represent any high-level model. All high level models meet this interface and can be used to extract low-level models from any high-level model.

type NodeBuilder

type NodeBuilder struct {
	Nodes   []*NodeEntry
	High    any
	Low     any
	Resolve bool // If set to true, all references will be rendered inline
}

NodeBuilder is a structure used by libopenapi high-level objects, to render themselves back to YAML. this allows high-level objects to be 'mutable' because all changes will be rendered out.

func NewNodeBuilder

func NewNodeBuilder(high any, low any) *NodeBuilder

NewNodeBuilder will create a new NodeBuilder instance, this is the only way to create a NodeBuilder. The function accepts a high level object and a low level object (need to be siblings/same type).

Using reflection, a map of every field in the high level object is created, ready to be rendered.

func (*NodeBuilder) AddYAMLNode

func (n *NodeBuilder) AddYAMLNode(parent *yaml.Node, entry *NodeEntry) *yaml.Node

AddYAMLNode will add a new *yaml.Node to the parent node, using the tag, key and value provided. If the value is nil, then the node will not be added. This method is recursive, so it will dig down into any non-scalar types.

func (*NodeBuilder) Render

func (n *NodeBuilder) Render() *yaml.Node

Render will render the NodeBuilder back to a YAML node, iterating over every NodeEntry defined

type NodeEntry

type NodeEntry struct {
	Tag         string
	Key         string
	Value       any
	StringValue string
	Line        int
	Style       yaml.Style
	RenderZero  bool
}

NodeEntry represents a single node used by NodeBuilder.

type Renderable

type Renderable interface {
	MarshalYAML() (interface{}, error)
}

Renderable is an interface that can be implemented by types that provide a custom MarshaYAML method.

type RenderableInline

type RenderableInline interface {
	MarshalYAMLInline() (interface{}, error)
}

RenderableInline is an interface that can be implemented by types that provide a custom MarshaYAML method.