resolver

Documentation

Index

• type Resolver
  • func NewResolver(index *index.SpecIndex) *Resolver
  • func (resolver *Resolver) CheckForCircularReferences() []*ResolvingError
  • func (resolver *Resolver) GetCircularErrors() []*index.CircularReferenceResult
  • func (resolver *Resolver) GetIndexesVisited() int
  • func (resolver *Resolver) GetJourneysTaken() int
  • func (resolver *Resolver) GetNonPolymorphicCircularErrors() []*index.CircularReferenceResult
  • func (resolver *Resolver) GetPolymorphicCircularErrors() []*index.CircularReferenceResult
  • func (resolver *Resolver) GetReferenceVisited() int
  • func (resolver *Resolver) GetRelativesSeen() int
  • func (resolver *Resolver) GetResolvingErrors() []*ResolvingError
  • func (resolver *Resolver) IgnoreArrayCircularReferences()
  • func (resolver *Resolver) IgnorePolymorphicCircularReferences()
  • func (resolver *Resolver) Resolve() []*ResolvingError
  • func (resolver *Resolver) VisitReference(ref *index.Reference, seen map[string]bool, journey []*index.Reference, ...) []*yaml.Node
• type ResolvingError
  • func (r *ResolvingError) Error() string

Examples

• NewResolver
• ResolvingError

Types

type Resolver

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

Resolver will use a *index.SpecIndex to stitch together a resolved root tree using all the discovered references in the doc.

func NewResolver

func NewResolver(index *index.SpecIndex) *Resolver

NewResolver will create a new resolver from a *index.SpecIndex

Example

Example of how to resolve the Stripe OpenAPI specification, and check for circular reference errors

// create a yaml.Node reference as a root node.
var rootNode yaml.Node

//  load in the Stripe OpenAPI spec (lots of polymorphic complexity in here)
stripeBytes, _ := os.ReadFile("../test_specs/stripe.yaml")

// unmarshal bytes into our rootNode.
_ = yaml.Unmarshal(stripeBytes, &rootNode)

// create a new spec index (resolver depends on it)
indexConfig := index.CreateClosedAPIIndexConfig()
idx := index.NewSpecIndexWithConfig(&rootNode, indexConfig)

// create a new resolver using the index.
resolver := NewResolver(idx)

// resolve the document, if there are circular reference errors, they are returned/
// WARNING: this is a destructive action and the rootNode will be PERMANENTLY altered and cannot be unresolved
circularErrors := resolver.Resolve()

// The Stripe API has a bunch of circular reference problems, mainly from polymorphism.
// So let's print them out.
//
fmt.Printf("There are %d circular reference errors, %d of them are polymorphic errors, %d are not",
	len(circularErrors), len(resolver.GetPolymorphicCircularErrors()), len(resolver.GetNonPolymorphicCircularErrors()))

Output:

There are 3 circular reference errors, 0 of them are polymorphic errors, 3 are not

func (*Resolver) CheckForCircularReferences

func (resolver *Resolver) CheckForCircularReferences() []*ResolvingError

CheckForCircularReferences Check for circular references, without resolving, a non-destructive run.

func (*Resolver) GetCircularErrors

func (resolver *Resolver) GetCircularErrors() []*index.CircularReferenceResult

GetCircularErrors returns all circular reference errors found.

func (*Resolver) GetIndexesVisited

func (resolver *Resolver) GetIndexesVisited() int

GetIndexesVisited returns the number of indexes visited by the resolver

func (*Resolver) GetJourneysTaken

func (resolver *Resolver) GetJourneysTaken() int

GetJourneysTaken returns the number of journeys taken by the resolver

func (*Resolver) GetNonPolymorphicCircularErrors

func (resolver *Resolver) GetNonPolymorphicCircularErrors() []*index.CircularReferenceResult

GetNonPolymorphicCircularErrors returns all circular errors that DO NOT stem from polymorphism

func (*Resolver) GetPolymorphicCircularErrors

func (resolver *Resolver) GetPolymorphicCircularErrors() []*index.CircularReferenceResult

GetPolymorphicCircularErrors returns all circular errors that stem from polymorphism

func (*Resolver) GetReferenceVisited

func (resolver *Resolver) GetReferenceVisited() int

GetReferenceVisited returns the number of references visited by the resolver

func (*Resolver) GetRelativesSeen

func (resolver *Resolver) GetRelativesSeen() int

GetRelativesSeen returns the number of siblings (nodes at the same level) seen for each reference found.

func (*Resolver) GetResolvingErrors

func (resolver *Resolver) GetResolvingErrors() []*ResolvingError

GetResolvingErrors returns all errors found during resolving

func (*Resolver) IgnoreArrayCircularReferences

func (resolver *Resolver) IgnoreArrayCircularReferences()

IgnoreArrayCircularReferences will ignore any circular references that stem from arrays. This must be set before any resolving is done.

func (*Resolver) IgnorePolymorphicCircularReferences

func (resolver *Resolver) IgnorePolymorphicCircularReferences()

IgnorePolymorphicCircularReferences will ignore any circular references that are polymorphic (oneOf, anyOf, allOf) This must be set before any resolving is done.

func (*Resolver) Resolve

func (resolver *Resolver) Resolve() []*ResolvingError

Resolve will resolve the specification, everything that is not polymorphic and not circular, will be resolved. this data can get big, it results in a massive duplication of data. This is a destructive method and will permanently re-organize the node tree. Make sure you have copied your original tree before running this (if you want to preserve original data)

func (*Resolver) VisitReference

func (resolver *Resolver) VisitReference(ref *index.Reference, seen map[string]bool, journey []*index.Reference, resolve bool) []*yaml.Node

VisitReference will visit a reference as part of a journey and will return resolved nodes.

type ResolvingError

type ResolvingError struct {
	// ErrorRef is the error thrown by the resolver
	ErrorRef error

	// Node is the *yaml.Node reference that contains the resolving error
	Node *yaml.Node

	// Path is the shortened journey taken by the resolver
	Path string

	// CircularReference is set if the error is a reference to the circular reference.
	CircularReference *index.CircularReferenceResult
}

ResolvingError represents an issue the resolver had trying to stitch the tree together.

Example

re := ResolvingError{
	ErrorRef: errors.New("je suis une erreur"),
	Node: &yaml.Node{
		Line:   5,
		Column: 21,
	},
	Path:              "#/definitions/JeSuisUneErreur",
	CircularReference: &index.CircularReferenceResult{},
}

fmt.Printf("%s", re.Error())

Output:

je suis une erreur: #/definitions/JeSuisUneErreur [5:21]

func (*ResolvingError) Error

func (r *ResolvingError) Error() string