index

package
v0.16.1 Latest Latest
Warning

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

 Go to latest Published: Apr 21, 2024 License: MIT Imports: 23 Imported by: 18

Documentation

Overview

Package index contains an OpenAPI indexer that will very quickly scan through an OpenAPI specification (all versions) and extract references to all the important nodes you might want to look up, as well as counts on total objects.

When extracting references, the index can determine if the reference is local to the file (recommended) or the reference is located in another local file, or a remote file. The index will then attempt to load in those remote files and look up the references there, or continue following the chain.

When the index loads in a local or remote file, it will also index that remote spec as well. This means everything is indexed and stored as a tree, depending on how deep the remote references go.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func GenerateCleanSpecConfigBaseURL added in v0.6.0 

func GenerateCleanSpecConfigBaseURL(baseURL *url.URL, dir string, includeFile bool) string

func HumanFileSize added in v0.13.13 

func HumanFileSize(size float64) string

func Round added in v0.13.13 

func Round(val float64, roundOn float64, places int) (newVal float64)

Types

type CanBeIndexed added in v0.13.0 

type CanBeIndexed interface {
	Index(config *SpecIndexConfig) (*SpecIndex, error)
}

CanBeIndexed is an interface that allows a file to be indexed.

type CircularReferenceResult 

type CircularReferenceResult struct {
	Journey             []*Reference
	ParentNode          *yaml.Node
	Start               *Reference
	LoopIndex           int
	LoopPoint           *Reference
	IsArrayResult       bool   // if this result comes from an array loop.
	PolymorphicType     string // which type of polymorphic loop is this? (oneOf, anyOf, allOf)
	IsPolymorphicResult bool   // if this result comes from a polymorphic loop.
	IsInfiniteLoop      bool   // if all the definitions in the reference loop are marked as required, this is an infinite circular reference, thus is not allowed.
}

CircularReferenceResult contains a circular reference found when traversing the graph.

func (*CircularReferenceResult) GenerateJourneyPath added in v0.0.5 

func (c *CircularReferenceResult) GenerateJourneyPath() string

GenerateJourneyPath generates a string representation of the journey taken to find the circular reference.

type ContextKey added in v0.13.0 

type ContextKey string
const (
	CurrentPathKey ContextKey = "currentPath"
	FoundIndexKey  ContextKey = "foundIndex"
)

type DescriptionReference 

type DescriptionReference struct {
	Content    string
	Path       string
	KeyNode    *yaml.Node
	Node       *yaml.Node
	ParentNode *yaml.Node
	IsSummary  bool
}

DescriptionReference holds data about a description that was found and where it was found.

type EnumReference 

type EnumReference struct {
	Node       *yaml.Node
	KeyNode    *yaml.Node
	Type       *yaml.Node
	Path       string
	SchemaNode *yaml.Node
	ParentNode *yaml.Node
}

type ExternalLookupFunction 

type ExternalLookupFunction func(id string) (foundNode *yaml.Node, rootNode *yaml.Node, lookupError error)

ExternalLookupFunction is for lookup functions that take a JSONSchema reference and tries to find that node in the URI based document. Decides if the reference is local, remote or in a file.

type ExtractedRef added in v0.13.0 

type ExtractedRef struct {
	Location string
	Type     RefType
}

func (*ExtractedRef) GetFile added in v0.13.0 

func (r *ExtractedRef) GetFile() string

GetFile returns the file path of the reference.

func (*ExtractedRef) GetReference added in v0.13.0 

func (r *ExtractedRef) GetReference() string

GetReference returns the reference path of the reference.

type FileExtension added in v0.13.0 

type FileExtension int

FileExtension is the type of file extension. 

const (
	YAML FileExtension = iota
	JSON
	UNSUPPORTED
)

func ExtractFileType added in v0.13.0 

func ExtractFileType(ref string) FileExtension

ExtractFileType returns the file extension of the reference.

type IndexingError 

type IndexingError struct {
	Err     error
	Node    *yaml.Node
	KeyNode *yaml.Node
	Path    string
}

IndexingError holds data about something that went wrong during indexing.

func (*IndexingError) Error 

func (i *IndexingError) Error() string

type LocalFS added in v0.13.0 

type LocalFS struct {
	Files syncmap.Map
	// contains filtered or unexported fields
}

LocalFS is a file system that indexes local files.

func NewLocalFSWithConfig added in v0.13.0 

func NewLocalFSWithConfig(config *LocalFSConfig) (*LocalFS, error)

NewLocalFSWithConfig creates a new LocalFS with the supplied configuration.

func (*LocalFS) GetErrors added in v0.13.0 

func (l *LocalFS) GetErrors() []error

GetErrors returns any errors that occurred during the indexing process.

func (*LocalFS) GetFiles added in v0.13.0 

func (l *LocalFS) GetFiles() map[string]RolodexFile

GetFiles returns the files that have been indexed. A map of RolodexFile objects keyed by the full path of the file.

func (*LocalFS) Open added in v0.13.0 

func (l *LocalFS) Open(name string) (fs.File, error)

Open opens a file, returning it or an error. If the file is not found, the error is of type *PathError.

type LocalFSConfig added in v0.13.0 

type LocalFSConfig struct {
	// the base directory to index
	BaseDirectory string

	// supply your own logger
	Logger *slog.Logger

	// supply a list of specific files to index only
	FileFilters []string

	// supply a custom fs.FS to use
	DirFS fs.FS

	// supply an index configuration to use
	IndexConfig *SpecIndexConfig
}

LocalFSConfig is the configuration for the LocalFS.

type LocalFile added in v0.13.0 

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

LocalFile is a file that has been indexed by the LocalFS. It implements the RolodexFile interface.

func (*LocalFile) Close added in v0.13.0 

func (l *LocalFile) Close() error

Close closes the file (doesn't do anything, returns no error)

func (*LocalFile) FullPath added in v0.13.0 

func (l *LocalFile) FullPath() string

FullPath returns the full path of the file.

func (*LocalFile) GetContent added in v0.13.0 

func (l *LocalFile) GetContent() string

GetContent returns the content of the file as a string.

func (*LocalFile) GetContentAsYAMLNode added in v0.13.0 

func (l *LocalFile) GetContentAsYAMLNode() (*yaml.Node, error)

GetContentAsYAMLNode returns the content of the file as a *yaml.Node. If something went wrong then an error is returned.

func (*LocalFile) GetErrors added in v0.13.0 

func (l *LocalFile) GetErrors() []error

GetErrors returns any errors that occurred during the indexing process.

func (*LocalFile) GetFileExtension added in v0.13.0 

func (l *LocalFile) GetFileExtension() FileExtension

GetFileExtension returns the FileExtension of the file.

func (*LocalFile) GetFullPath added in v0.13.0 

func (l *LocalFile) GetFullPath() string

GetFullPath returns the full path of the file.

func (*LocalFile) GetIndex added in v0.13.0 

func (l *LocalFile) GetIndex() *SpecIndex

GetIndex returns the *SpecIndex for the file.

func (*LocalFile) Index added in v0.13.0 

func (l *LocalFile) Index(config *SpecIndexConfig) (*SpecIndex, error)

Index returns the *SpecIndex for the file. If the index has not been created, it will be created (indexed)

func (*LocalFile) IsDir added in v0.13.0 

func (l *LocalFile) IsDir() bool

IsDir returns true if the file is a directory, it always returns false

func (*LocalFile) ModTime added in v0.13.0 

func (l *LocalFile) ModTime() time.Time

ModTime returns the modification time of the file.

func (*LocalFile) Mode added in v0.13.0 

func (l *LocalFile) Mode() fs.FileMode

Mode returns the file mode bits for the file.

func (*LocalFile) Name added in v0.13.0 

func (l *LocalFile) Name() string

Name returns the name of the file.

func (*LocalFile) Read added in v0.13.0 

func (l *LocalFile) Read(b []byte) (int, error)

Read reads the file into a byte slice, makes it compatible with io.Reader.

func (*LocalFile) Size added in v0.13.0 

func (l *LocalFile) Size() int64

Size returns the size of the file.

func (*LocalFile) Stat added in v0.13.0 

func (l *LocalFile) Stat() (fs.FileInfo, error)

Stat returns the FileInfo for the file.

func (*LocalFile) Sys added in v0.13.0 

func (l *LocalFile) Sys() interface{}

Sys returns the underlying data source (always returns nil)

type NodeOrigin added in v0.13.12 

type NodeOrigin struct {
	// Node is the node in question
	Node *yaml.Node `json:"-"`

	// Line is yhe original line of where the node was found in the original file
	Line int `json:"line" yaml:"line"`

	// Column is the original column of where the node was found in the original file
	Column int `json:"column" yaml:"column"`

	// AbsoluteLocation is the absolute path to the reference was extracted from.
	// This can either be an absolute path to a file, or a URL.
	AbsoluteLocation string `json:"absolute_location" yaml:"absolute_location"`

	// Index is the index that contains the node that was located in.
	Index *SpecIndex `json:"-" yaml:"-"`
}

NodeOrigin represents where a node has come from within a specification. This is not useful for single file specs, but becomes very, very important when dealing with exploded specifications, and we need to know where in the mass of files a node has come from.

type ObjectReference added in v0.4.8 

type ObjectReference struct {
	Node       *yaml.Node
	KeyNode    *yaml.Node
	Path       string
	ParentNode *yaml.Node
}

type RefType added in v0.13.0 

type RefType int
const (
	Local RefType = iota
	File
	HTTP
)

type Reference 

type Reference struct {
	FullDefinition        string
	Definition            string
	Name                  string
	Node                  *yaml.Node
	KeyNode               *yaml.Node
	ParentNode            *yaml.Node
	ParentNodeSchemaType  string   // used to determine if the parent node is an array or not.
	ParentNodeTypes       []string // used to capture deep journeys, if any item is an array, we need to know.
	Resolved              bool
	Circular              bool
	Seen                  bool
	IsRemote              bool
	Index                 *SpecIndex // index that contains this reference.
	RemoteLocation        string
	Path                  string              // this won't always be available.
	RequiredRefProperties map[string][]string // definition names (eg, #/definitions/One) to a list of required properties on this definition which reference that definition
}

Reference is a wrapper around *yaml.Node results to make things more manageable when performing algorithms on data models. the *yaml.Node def is just a bit too low level for tracking state.

func FindComponent added in v0.13.0 

func FindComponent(root *yaml.Node, componentId, absoluteFilePath string, index *SpecIndex) *Reference

type ReferenceMapped 

type ReferenceMapped struct {
	OriginalReference *Reference
	Reference         *Reference
	Definition        string
	FullDefinition    string
}

ReferenceMapped is a helper struct for mapped references put into sequence (we lose the key)

type RemoteFS added in v0.13.0 

type RemoteFS struct {
	RemoteHandlerFunc utils.RemoteURLHandler
	Files             syncmap.Map
	ProcessingFiles   syncmap.Map
	FetchTime         int64
	FetchChannel      chan *RemoteFile
	// contains filtered or unexported fields
}

RemoteFS is a file system that indexes remote files. It implements the fs.FS interface. Files are located remotely and served via HTTP.

func NewRemoteFSWithConfig added in v0.13.0 

func NewRemoteFSWithConfig(specIndexConfig *SpecIndexConfig) (*RemoteFS, error)

NewRemoteFSWithConfig creates a new RemoteFS using the supplied SpecIndexConfig.

func NewRemoteFSWithRootURL added in v0.13.0 

func NewRemoteFSWithRootURL(rootURL string) (*RemoteFS, error)

NewRemoteFSWithRootURL creates a new RemoteFS using the supplied root URL.

func (*RemoteFS) GetErrors added in v0.13.0 

func (i *RemoteFS) GetErrors() []error

GetErrors returns any errors that occurred during the indexing process.

func (*RemoteFS) GetFiles added in v0.13.0 

func (i *RemoteFS) GetFiles() map[string]RolodexFile

GetFiles returns the files that have been indexed.

func (*RemoteFS) Open added in v0.13.0 

func (i *RemoteFS) Open(remoteURL string) (fs.File, error)

Open opens a file, returning it or an error. If the file is not found, the error is of type *PathError.

func (*RemoteFS) SetIndexConfig added in v0.13.0 

func (i *RemoteFS) SetIndexConfig(config *SpecIndexConfig)

SetIndexConfig sets the index configuration.

func (*RemoteFS) SetRemoteHandlerFunc added in v0.13.0 

func (i *RemoteFS) SetRemoteHandlerFunc(handlerFunc utils.RemoteURLHandler)

SetRemoteHandlerFunc sets the remote handler function.

type RemoteFile added in v0.13.0 

type RemoteFile struct {
	URL *url.URL
	// contains filtered or unexported fields
}

RemoteFile is a file that has been indexed by the RemoteFS. It implements the RolodexFile interface.

func (*RemoteFile) Close added in v0.13.0 

func (f *RemoteFile) Close() error

Close closes the file (doesn't do anything, returns no error)

func (*RemoteFile) GetContent added in v0.13.0 

func (f *RemoteFile) GetContent() string

GetContent returns the content of the file as a string.

func (*RemoteFile) GetContentAsYAMLNode added in v0.13.0 

func (f *RemoteFile) GetContentAsYAMLNode() (*yaml.Node, error)

GetContentAsYAMLNode returns the content of the file as a yaml.Node.

func (*RemoteFile) GetErrors added in v0.13.0 

func (f *RemoteFile) GetErrors() []error

GetErrors returns any errors that occurred while reading the file.

func (*RemoteFile) GetFileExtension added in v0.13.0 

func (f *RemoteFile) GetFileExtension() FileExtension

GetFileExtension returns the file extension of the file.

func (*RemoteFile) GetFileName added in v0.13.0 

func (f *RemoteFile) GetFileName() string

GetFileName returns the name of the file.

func (*RemoteFile) GetFullPath added in v0.13.0 

func (f *RemoteFile) GetFullPath() string

GetFullPath returns the full path of the file.

func (*RemoteFile) GetIndex added in v0.13.0 

func (f *RemoteFile) GetIndex() *SpecIndex

GetIndex returns the index for the file.

func (*RemoteFile) GetLastModified added in v0.13.0 

func (f *RemoteFile) GetLastModified() time.Time

GetLastModified returns the last modified time of the file.

func (*RemoteFile) Index added in v0.13.0 

func (f *RemoteFile) Index(config *SpecIndexConfig) (*SpecIndex, error)

Index indexes the file and returns a *SpecIndex, any errors are returned as well.

func (*RemoteFile) IsDir added in v0.13.0 

func (f *RemoteFile) IsDir() bool

IsDir returns true if the file is a directory.

func (*RemoteFile) ModTime added in v0.13.0 

func (f *RemoteFile) ModTime() time.Time

ModTime returns the modification time of the file.

func (*RemoteFile) Mode added in v0.13.0 

func (f *RemoteFile) Mode() fs.FileMode

Mode returns the file mode bits for the file.

func (*RemoteFile) Name added in v0.13.0 

func (f *RemoteFile) Name() string

Name returns the name of the file.

func (*RemoteFile) Read added in v0.13.0 

func (f *RemoteFile) Read(b []byte) (int, error)

Read reads the file. Makes it compatible with io.Reader.

func (*RemoteFile) Size added in v0.13.0 

func (f *RemoteFile) Size() int64

Size returns the size of the file.

func (*RemoteFile) Stat added in v0.13.0 

func (f *RemoteFile) Stat() (fs.FileInfo, error)

Stat returns the FileInfo for the file.

func (*RemoteFile) Sys added in v0.13.0 

func (f *RemoteFile) Sys() interface{}

Sys returns the underlying data source (always returns nil)

type Resolver added in v0.13.0 

type Resolver struct {
	IgnorePoly  bool
	IgnoreArray bool
	// 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 added in v0.13.0 

func NewResolver(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 := CreateClosedAPIIndexConfig()
idx := 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 is %d circular reference error, %d of them are polymorphic errors, %d are not\n"+
	"with a total pf %d safe circular references.\n",
	len(circularErrors), len(resolver.GetPolymorphicCircularErrors()), len(resolver.GetNonPolymorphicCircularErrors()),
	len(resolver.GetSafeCircularReferences()))

Output:

There is 1 circular reference error, 0 of them are polymorphic errors, 1 are not
with a total pf 25 safe circular references.

func (*Resolver) CheckForCircularReferences added in v0.13.0 

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

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

func (*Resolver) GetCircularReferences added in v0.13.0 

func (resolver *Resolver) GetCircularReferences() []*CircularReferenceResult

func (*Resolver) GetIgnoredCircularArrayReferences added in v0.13.0 

func (resolver *Resolver) GetIgnoredCircularArrayReferences() []*CircularReferenceResult

GetIgnoredCircularArrayReferences returns all ignored circular references that are arrays

func (*Resolver) GetIgnoredCircularPolyReferences added in v0.13.0 

func (resolver *Resolver) GetIgnoredCircularPolyReferences() []*CircularReferenceResult

GetIgnoredCircularPolyReferences returns all ignored circular references that are polymorphic

func (*Resolver) GetIndexesVisited added in v0.13.0 

func (resolver *Resolver) GetIndexesVisited() int

GetIndexesVisited returns the number of indexes visited by the resolver

func (*Resolver) GetInfiniteCircularReferences added in v0.13.0 

func (resolver *Resolver) GetInfiniteCircularReferences() []*CircularReferenceResult

GetInfiniteCircularReferences returns all circular reference errors found that are infinite / unrecoverable

func (*Resolver) GetJourneysTaken added in v0.13.0 

func (resolver *Resolver) GetJourneysTaken() int

GetJourneysTaken returns the number of journeys taken by the resolver

func (*Resolver) GetNonPolymorphicCircularErrors added in v0.13.0 

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

GetNonPolymorphicCircularErrors returns all circular errors that DO NOT stem from polymorphism

func (*Resolver) GetPolymorphicCircularErrors added in v0.13.0 

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

GetPolymorphicCircularErrors returns all circular errors that stem from polymorphism

func (*Resolver) GetReferenceVisited added in v0.13.0 

func (resolver *Resolver) GetReferenceVisited() int

GetReferenceVisited returns the number of references visited by the resolver

func (*Resolver) GetRelativesSeen added in v0.13.0 

func (resolver *Resolver) GetRelativesSeen() int

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

func (*Resolver) GetResolvingErrors added in v0.13.0 

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

GetResolvingErrors returns all errors found during resolving

func (*Resolver) GetSafeCircularReferences added in v0.13.0 

func (resolver *Resolver) GetSafeCircularReferences() []*CircularReferenceResult

GetSafeCircularReferences returns all circular reference errors found.

func (*Resolver) IgnoreArrayCircularReferences added in v0.13.0 

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 added in v0.13.0 

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 added in v0.13.0 

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) ResolvePendingNodes added in v0.13.21 

func (resolver *Resolver) ResolvePendingNodes()

func (*Resolver) VisitReference added in v0.13.0 

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

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

type ResolvingError added in v0.13.0 

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 *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: &CircularReferenceResult{},
}

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

Output:

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

func (*ResolvingError) Error added in v0.13.0 

func (r *ResolvingError) Error() string

type Rolodex added in v0.13.0 

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

Rolodex is a file system abstraction that allows for the indexing of multiple file systems and the ability to resolve references across those file systems. It is used to hold references to external files, and the indexes they hold. The rolodex is the master lookup for all references.

func NewRolodex added in v0.13.0 

func NewRolodex(indexConfig *SpecIndexConfig) *Rolodex

NewRolodex creates a new rolodex with the provided index configuration.

func (*Rolodex) AddExternalIndex added in v0.13.12 

func (r *Rolodex) AddExternalIndex(idx *SpecIndex, location string)

func (*Rolodex) AddIndex added in v0.13.12 

func (r *Rolodex) AddIndex(idx *SpecIndex)

func (*Rolodex) AddLocalFS added in v0.13.0 

func (r *Rolodex) AddLocalFS(baseDir string, fileSystem fs.FS)

AddLocalFS adds a local file system to the rolodex.

func (*Rolodex) AddRemoteFS added in v0.13.0 

func (r *Rolodex) AddRemoteFS(baseURL string, fileSystem fs.FS)

AddRemoteFS adds a remote file system to the rolodex.

func (*Rolodex) BuildIndexes added in v0.13.0 

func (r *Rolodex) BuildIndexes()

BuildIndexes builds the indexes in the rolodex, this is generally not required unless manually building a rolodex.

func (*Rolodex) CheckForCircularReferences added in v0.13.0 

func (r *Rolodex) CheckForCircularReferences()

CheckForCircularReferences checks for circular references in the rolodex.

func (*Rolodex) FindNodeOrigin added in v0.13.12 

func (r *Rolodex) FindNodeOrigin(node *yaml.Node) *NodeOrigin

FindNodeOrigin searches all indexes for the origin of a node. If the node is found, a NodeOrigin is returned, otherwise nil is returned.

func (*Rolodex) GetCaughtErrors added in v0.13.0 

func (r *Rolodex) GetCaughtErrors() []error

GetCaughtErrors returns all the errors that were caught during the indexing process.

func (*Rolodex) GetIgnoredCircularReferences added in v0.13.0 

func (r *Rolodex) GetIgnoredCircularReferences() []*CircularReferenceResult

GetIgnoredCircularReferences returns a list of circular references that were ignored during the indexing process. These can be array or polymorphic references.

func (*Rolodex) GetIndexes added in v0.13.0 

func (r *Rolodex) GetIndexes() []*SpecIndex

GetIndexes returns all the indexes in the rolodex.

func (*Rolodex) GetIndexingDuration added in v0.13.0 

func (r *Rolodex) GetIndexingDuration() time.Duration

GetIndexingDuration returns the duration it took to index the rolodex.

func (*Rolodex) GetRootIndex added in v0.13.0 

func (r *Rolodex) GetRootIndex() *SpecIndex

GetRootIndex returns the root index of the rolodex (the entry point, the main document)

func (*Rolodex) GetRootNode added in v0.13.3 

func (r *Rolodex) GetRootNode() *yaml.Node

GetRootNode returns the root index of the rolodex (the entry point, the main document)

func (*Rolodex) IndexTheRolodex added in v0.13.0 

func (r *Rolodex) IndexTheRolodex() error

IndexTheRolodex indexes the rolodex, building out the indexes for each file, and then building the root index.

func (*Rolodex) Open added in v0.13.0 

func (r *Rolodex) Open(location string) (RolodexFile, error)

Open opens a file in the rolodex, and returns a RolodexFile.

func (*Rolodex) Resolve added in v0.13.0 

func (r *Rolodex) Resolve()

Resolve resolves references in the rolodex.

func (*Rolodex) RolodexFileSize added in v0.13.13 

func (r *Rolodex) RolodexFileSize() int64

func (*Rolodex) RolodexFileSizeAsString added in v0.13.13 

func (r *Rolodex) RolodexFileSizeAsString() string

func (*Rolodex) RolodexTotalFiles added in v0.13.13 

func (r *Rolodex) RolodexTotalFiles() int

func (*Rolodex) SetRootNode added in v0.13.0 

func (r *Rolodex) SetRootNode(node *yaml.Node)

SetRootNode sets the root node of the rolodex (the entry point, the main document)

type RolodexFS added in v0.13.0 

type RolodexFS interface {
	Open(name string) (fs.File, error)
	GetFiles() map[string]RolodexFile
}

RolodexFS is an interface that represents a RolodexFS, is the same interface as `fs.FS`, except it also exposes a GetFiles() signature, to extract all files in the FS.

type RolodexFile added in v0.13.0 

type RolodexFile interface {
	GetContent() string
	GetFileExtension() FileExtension
	GetFullPath() string
	GetErrors() []error
	GetContentAsYAMLNode() (*yaml.Node, error)
	GetIndex() *SpecIndex
	Name() string
	ModTime() time.Time
	IsDir() bool
	Sys() any
	Size() int64
	Mode() os.FileMode
}

RolodexFile is an interface that represents a file in the rolodex. It combines multiple `fs` interfaces like `fs.FileInfo` and `fs.File` into one interface, so the same struct can be used for everything.

type SpecIndex 

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

SpecIndex is a complete pre-computed index of the entire specification. Numbers are pre-calculated and quick direct access to paths, operations, tags are all available. No need to walk the entire node tree in rules, everything is pre-walked if you need it.

func NewSpecIndex 

func NewSpecIndex(rootNode *yaml.Node) *SpecIndex

NewSpecIndex will create a new index of an OpenAPI or Swagger spec. It's not resolved or converted into anything other than a raw index of every node for every content type in the specification. This process runs as fast as possible so dependencies looking through the tree, don't need to walk the entire thing over, and over.

This creates a new index using a default 'open' configuration. This means if a BaseURL or BasePath are supplied the rolodex will automatically read those files or open those h

Example

Example of how to load in an OpenAPI Specification and index it. 

// define a rootNode to hold our raw spec AST.
var rootNode yaml.Node

// load in the stripe OpenAPI specification into bytes (it's pretty meaty)
stripeSpec, _ := os.ReadFile("../test_specs/stripe.yaml")

// unmarshal spec into our rootNode
_ = yaml.Unmarshal(stripeSpec, &rootNode)

// create a new specification index.
index := NewSpecIndexWithConfig(&rootNode, CreateOpenAPIIndexConfig())

// print out some statistics
fmt.Printf("There are %d references\n"+
	"%d paths\n"+
	"%d operations\n"+
	"%d component schemas\n"+
	"%d reference schemas\n"+
	"%d inline schemas\n"+
	"%d inline schemas that are objects or arrays\n"+
	"%d total schemas\n"+
	"%d enums\n"+
	"%d polymorphic references",
	len(index.GetAllCombinedReferences()),
	len(index.GetAllPaths()),
	index.GetOperationCount(),
	len(index.GetAllComponentSchemas()),
	len(index.GetAllReferenceSchemas()),
	len(index.GetAllInlineSchemas()),
	len(index.GetAllInlineSchemaObjects()),
	len(index.GetAllSchemas()),
	len(index.GetAllEnums()),
	len(index.GetPolyOneOfReferences())+len(index.GetPolyAnyOfReferences()))

Output:

There are 871 references
336 paths
494 operations
871 component schemas
2712 reference schemas
15928 inline schemas
3857 inline schemas that are objects or arrays
19511 total schemas
2579 enums
1023 polymorphic references

func NewSpecIndexWithConfig added in v0.6.0 

func NewSpecIndexWithConfig(rootNode *yaml.Node, config *SpecIndexConfig) *SpecIndex

NewSpecIndexWithConfig will create a new index of an OpenAPI or Swagger spec. It uses the same logic as NewSpecIndex except it sets a base URL for resolving relative references, except it also allows for granular control over how the index is set up.

func (*SpecIndex) AllowCircularReferenceResolving added in v0.0.5 

func (index *SpecIndex) AllowCircularReferenceResolving() bool

AllowCircularReferenceResolving will return a bit that allows developers to determine what to do with circular refs.

func (*SpecIndex) BuildIndex added in v0.9.0 

func (index *SpecIndex) BuildIndex()

BuildIndex will run all the count operations required to build up maps of everything. It's what makes the index useful for looking up things, the count operations are all run in parallel and then the final calculations are run the index is ready.

func (*SpecIndex) ExtractComponentsFromRefs 

func (index *SpecIndex) ExtractComponentsFromRefs(refs []*Reference) []*Reference

ExtractComponentsFromRefs returns located components from references. The returned nodes from here can be used for resolving as they contain the actual object properties.

func (*SpecIndex) ExtractExternalDocuments 

func (index *SpecIndex) ExtractExternalDocuments(node *yaml.Node) []*Reference

ExtractExternalDocuments will extract the number of externalDocs nodes found in the document.

func (*SpecIndex) ExtractRefs 

func (index *SpecIndex) ExtractRefs(node, parent *yaml.Node, seenPath []string, level int, poly bool, pName string) []*Reference

ExtractRefs will return a deduplicated slice of references for every unique ref found in the document. The total number of refs, will generally be much higher, you can extract those from GetRawReferenceCount()

func (*SpecIndex) FindComponent 

func (index *SpecIndex) FindComponent(componentId string) *Reference

FindComponent will locate a component by its reference, returns nil if nothing is found. This method will recurse through remote, local and file references. For each new external reference a new index will be created. These indexes can then be traversed recursively.

func (*SpecIndex) FindComponentInRoot added in v0.0.5 

func (index *SpecIndex) FindComponentInRoot(componentId string) *Reference

func (*SpecIndex) FindNodeOrigin added in v0.13.12 

func (index *SpecIndex) FindNodeOrigin(node *yaml.Node) *NodeOrigin

FindNodeOrigin searches this index for a matching node. If the node is found, a NodeOrigin is returned, otherwise nil is returned.

func (*SpecIndex) GetAllCallbacks 

func (index *SpecIndex) GetAllCallbacks() map[string]*Reference

GetAllCallbacks will return all links found in the document (under components)

func (*SpecIndex) GetAllCombinedReferences 

func (index *SpecIndex) GetAllCombinedReferences() map[string]*Reference

GetAllCombinedReferences will return the number of unique and polymorphic references discovered.

func (*SpecIndex) GetAllComponentSchemas added in v0.5.0 

func (index *SpecIndex) GetAllComponentSchemas() map[string]*Reference

GetAllComponentSchemas will return all schemas defined in the components section of the document.

func (*SpecIndex) GetAllDescriptions 

func (index *SpecIndex) GetAllDescriptions() []*DescriptionReference

GetAllDescriptions will return all descriptions found in the document

func (*SpecIndex) GetAllDescriptionsCount 

func (index *SpecIndex) GetAllDescriptionsCount() int

GetAllDescriptionsCount will collect together every single description found in the document

func (*SpecIndex) GetAllEnums 

func (index *SpecIndex) GetAllEnums() []*EnumReference

GetAllEnums will return all enums found in the document

func (*SpecIndex) GetAllExamples 

func (index *SpecIndex) GetAllExamples() map[string]*Reference

GetAllExamples will return all examples found in the document (under components)

func (*SpecIndex) GetAllExternalDocuments 

func (index *SpecIndex) GetAllExternalDocuments() map[string]*Reference

GetAllExternalDocuments will return all external documents found

func (*SpecIndex) GetAllHeaders 

func (index *SpecIndex) GetAllHeaders() map[string]*Reference

GetAllHeaders will return all headers found in the document (under components)

func (*SpecIndex) GetAllInlineSchemaObjects added in v0.5.0 

func (index *SpecIndex) GetAllInlineSchemaObjects() []*Reference

GetAllInlineSchemaObjects will return all schemas that are inline (not inside components) and that are also typed as 'object' or 'array' (not primitives).

func (*SpecIndex) GetAllInlineSchemas added in v0.5.0 

func (index *SpecIndex) GetAllInlineSchemas() []*Reference

GetAllInlineSchemas will return all schemas defined in the components section of the document. 

func (index *SpecIndex) GetAllLinks() map[string]*Reference

GetAllLinks will return all links found in the document (under components)

func (*SpecIndex) GetAllObjectsWithProperties added in v0.4.8 

func (index *SpecIndex) GetAllObjectsWithProperties() []*ObjectReference

GetAllObjectsWithProperties will return all objects with properties found in the document

func (*SpecIndex) GetAllOperationsServers 

func (index *SpecIndex) GetAllOperationsServers() map[string]map[string][]*Reference

GetAllOperationsServers will return all operation overrides for servers.

func (*SpecIndex) GetAllParameters 

func (index *SpecIndex) GetAllParameters() map[string]*Reference

GetAllParameters will return all parameters found in the document (under components)

func (*SpecIndex) GetAllParametersFromOperations 

func (index *SpecIndex) GetAllParametersFromOperations() map[string]map[string]map[string][]*Reference

GetAllParametersFromOperations will return all paths indexed in the document

func (*SpecIndex) GetAllPaths 

func (index *SpecIndex) GetAllPaths() map[string]map[string]*Reference

GetAllPaths will return all paths indexed in the document

func (*SpecIndex) GetAllReferenceSchemas added in v0.9.8 

func (index *SpecIndex) GetAllReferenceSchemas() []*Reference

GetAllReferenceSchemas will return all schemas that are not inline, but $ref'd from somewhere.

func (*SpecIndex) GetAllReferences 

func (index *SpecIndex) GetAllReferences() map[string]*Reference

GetAllReferences will return every reference found in the spec, after being de-duplicated.

func (*SpecIndex) GetAllRequestBodies 

func (index *SpecIndex) GetAllRequestBodies() map[string]*Reference

GetAllRequestBodies will return all requestBodies found in the document (under components)

func (*SpecIndex) GetAllResponses 

func (index *SpecIndex) GetAllResponses() map[string]*Reference

GetAllResponses will return all responses found in the document (under components)

func (*SpecIndex) GetAllRootServers 

func (index *SpecIndex) GetAllRootServers() []*Reference

GetAllRootServers will return all root servers defined

func (*SpecIndex) GetAllSchemas 

func (index *SpecIndex) GetAllSchemas() []*Reference

GetAllSchemas will return references to all schemas found in the document both inline and those under components The first elements of at the top of the slice, are all the inline references (using GetAllInlineSchemas), and then following on are all the references extracted from the components section (using GetAllComponentSchemas). finally all the references that are not inline, but marked as $ref in the document are returned (using GetAllReferenceSchemas). the results are sorted by line number.

func (*SpecIndex) GetAllSecuritySchemes 

func (index *SpecIndex) GetAllSecuritySchemes() map[string]*Reference

GetAllSecuritySchemes will return all security schemes / definitions found in the document.

func (*SpecIndex) GetAllSequencedReferences 

func (index *SpecIndex) GetAllSequencedReferences() []*Reference

GetAllSequencedReferences will return every reference (in sequence) that was found (non-polymorphic)

func (*SpecIndex) GetAllSummaries 

func (index *SpecIndex) GetAllSummaries() []*DescriptionReference

GetAllSummaries will return all summaries found in the document

func (*SpecIndex) GetAllSummariesCount 

func (index *SpecIndex) GetAllSummariesCount() int

GetAllSummariesCount will collect together every single summary found in the document

func (*SpecIndex) GetCache added in v0.13.0 

func (index *SpecIndex) GetCache() *syncmap.Map

func (*SpecIndex) GetCircularReferences added in v0.0.5 

func (index *SpecIndex) GetCircularReferences() []*CircularReferenceResult

GetCircularReferences will return any circular reference results that were found by the resolver.

func (*SpecIndex) GetComponentParameterCount 

func (index *SpecIndex) GetComponentParameterCount() int

GetComponentParameterCount returns the number of parameter components defined

func (*SpecIndex) GetComponentSchemaCount 

func (index *SpecIndex) GetComponentSchemaCount() int

GetComponentSchemaCount will return the number of schemas located in the 'components' or 'definitions' node.

func (*SpecIndex) GetConfig added in v0.12.1 

func (index *SpecIndex) GetConfig() *SpecIndexConfig

GetConfig returns the SpecIndexConfig for this index.

func (*SpecIndex) GetDiscoveredReferences 

func (index *SpecIndex) GetDiscoveredReferences() map[string]*Reference

GetDiscoveredReferences will return all unique references found in the spec

func (*SpecIndex) GetGlobalCallbacksCount added in v0.0.5 

func (index *SpecIndex) GetGlobalCallbacksCount() int

GetGlobalCallbacksCount for each response of each operation method, multiple callbacks can be defined

func (*SpecIndex) GetGlobalLinksCount 

func (index *SpecIndex) GetGlobalLinksCount() int

GetGlobalLinksCount for each response of each operation method, multiple callbacks can be defined

func (*SpecIndex) GetGlobalTagsCount 

func (index *SpecIndex) GetGlobalTagsCount() int

GetGlobalTagsCount will return the number of tags found in the top level 'tags' node of the document.

func (*SpecIndex) GetGlobalTagsNode 

func (index *SpecIndex) GetGlobalTagsNode() *yaml.Node

GetGlobalTagsNode returns document root tags node.

func (*SpecIndex) GetIgnoredArrayCircularReferences added in v0.15.0 

func (index *SpecIndex) GetIgnoredArrayCircularReferences() []*CircularReferenceResult

GetIgnoredArrayCircularReferences will return any array based circular references that were 'ignored' by using the `IgnoreArrayCircularReferences` configuration option.

func (*SpecIndex) GetIgnoredPolymorphicCircularReferences added in v0.15.0 

func (index *SpecIndex) GetIgnoredPolymorphicCircularReferences() []*CircularReferenceResult

GetIgnoredPolymorphicCircularReferences will return any polymorphic circular references that were 'ignored' by using the `IgnorePolymorphicCircularReferences` configuration option.

func (*SpecIndex) GetInlineDuplicateParamCount 

func (index *SpecIndex) GetInlineDuplicateParamCount() int

GetInlineDuplicateParamCount returns the number of inline duplicate parameters (operation params)

func (*SpecIndex) GetInlineOperationDuplicateParameters 

func (index *SpecIndex) GetInlineOperationDuplicateParameters() map[string][]*Reference

GetInlineOperationDuplicateParameters will return a map of duplicates located in operation parameters.

func (*SpecIndex) GetInlineUniqueParamCount 

func (index *SpecIndex) GetInlineUniqueParamCount() int

GetInlineUniqueParamCount returns the number of unique inline parameters (operation params)

func (*SpecIndex) GetLinesWithReferences 

func (index *SpecIndex) GetLinesWithReferences() map[int]bool

GetLinesWithReferences will return a map of lines that have a $ref

func (*SpecIndex) GetLogger added in v0.13.0 

func (index *SpecIndex) GetLogger() *slog.Logger

func (*SpecIndex) GetMappedReferences 

func (index *SpecIndex) GetMappedReferences() map[string]*Reference

GetMappedReferences will return all references that were mapped successfully to actual property nodes. this collection is completely unsorted, traversing it may produce random results when resolving it and encountering circular references can change results depending on where in the collection the resolver started its journey through the index.

func (*SpecIndex) GetMappedReferencesSequenced 

func (index *SpecIndex) GetMappedReferencesSequenced() []*ReferenceMapped

GetMappedReferencesSequenced will return all references that were mapped successfully to nodes, performed in sequence as they were read in from the document.

func (*SpecIndex) GetNode added in v0.13.12 

func (index *SpecIndex) GetNode(line int, column int) (*yaml.Node, bool)

GetNode returns a node from the spec based on a line and column. The second return var bool is true if the node was found, false if not.

func (*SpecIndex) GetNodeMap added in v0.15.0 

func (index *SpecIndex) GetNodeMap() map[int]map[int]*yaml.Node

func (*SpecIndex) GetOperationCount 

func (index *SpecIndex) GetOperationCount() int

GetOperationCount returns the number of operations (for all paths) located in the document

func (*SpecIndex) GetOperationParameterReferences 

func (index *SpecIndex) GetOperationParameterReferences() map[string]map[string]map[string][]*Reference

GetOperationParameterReferences will return all references to operation parameters

func (*SpecIndex) GetOperationParametersIndexErrors 

func (index *SpecIndex) GetOperationParametersIndexErrors() []error

GetOperationParametersIndexErrors any errors that occurred when indexing operation parameters

func (*SpecIndex) GetOperationTags 

func (index *SpecIndex) GetOperationTags() map[string]map[string][]*Reference

GetOperationTags will return all references to all tags found in operations.

func (*SpecIndex) GetOperationTagsCount 

func (index *SpecIndex) GetOperationTagsCount() int

GetOperationTagsCount will return the number of operation tags found (tags referenced in operations)

func (*SpecIndex) GetOperationsParameterCount 

func (index *SpecIndex) GetOperationsParameterCount() int

GetOperationsParameterCount returns the number of parameters defined in paths and operations. this method looks in top level (path level) and inside each operation (get, post etc.). Parameters can be hiding within multiple places.

func (*SpecIndex) GetParametersNode 

func (index *SpecIndex) GetParametersNode() *yaml.Node

GetParametersNode will return the schema's node found in the spec

func (*SpecIndex) GetPathCount 

func (index *SpecIndex) GetPathCount() int

GetPathCount will return the number of paths found in the spec

func (*SpecIndex) GetPathsNode 

func (index *SpecIndex) GetPathsNode() *yaml.Node

GetPathsNode returns document root node.

func (*SpecIndex) GetPolyAllOfReferences 

func (index *SpecIndex) GetPolyAllOfReferences() []*Reference

GetPolyAllOfReferences will return every 'allOf' polymorphic reference in the doc

func (*SpecIndex) GetPolyAnyOfReferences 

func (index *SpecIndex) GetPolyAnyOfReferences() []*Reference

GetPolyAnyOfReferences will return every 'anyOf' polymorphic reference in the doc

func (*SpecIndex) GetPolyOneOfReferences 

func (index *SpecIndex) GetPolyOneOfReferences() []*Reference

GetPolyOneOfReferences will return every 'allOf' polymorphic reference in the doc

func (*SpecIndex) GetPolyReferences 

func (index *SpecIndex) GetPolyReferences() map[string]*Reference

GetPolyReferences will return every polymorphic reference in the doc

func (*SpecIndex) GetRawReferenceCount 

func (index *SpecIndex) GetRawReferenceCount() int

GetRawReferenceCount will return the number of raw references located in the document.

func (*SpecIndex) GetRawReferencesSequenced added in v0.15.0 

func (index *SpecIndex) GetRawReferencesSequenced() []*Reference

GetRawReferencesSequenced returns a slice of every single reference found in the document, extracted raw from the doc returned in the exact order they were found in the document.

func (*SpecIndex) GetReferenceIndexErrors added in v0.0.5 

func (index *SpecIndex) GetReferenceIndexErrors() []error

GetReferenceIndexErrors will return any errors that occurred when indexing references

func (*SpecIndex) GetReferencesWithSiblings 

func (index *SpecIndex) GetReferencesWithSiblings() map[string]Reference

GetReferencesWithSiblings will return a map of all the references with sibling nodes (illegal)

func (*SpecIndex) GetRefsByLine 

func (index *SpecIndex) GetRefsByLine() map[string]map[int]bool

GetRefsByLine will return all references and the lines at which they were found.

func (*SpecIndex) GetResolver added in v0.13.0 

func (index *SpecIndex) GetResolver() *Resolver

GetResolver returns the resolver for this index.

func (*SpecIndex) GetRolodex added in v0.13.12 

func (index *SpecIndex) GetRolodex() *Rolodex

func (*SpecIndex) GetRootNode 

func (index *SpecIndex) GetRootNode() *yaml.Node

GetRootNode returns document root node.

func (*SpecIndex) GetRootSecurityNode 

func (index *SpecIndex) GetRootSecurityNode() *yaml.Node

GetRootSecurityNode will return the root security node

func (*SpecIndex) GetRootSecurityReferences 

func (index *SpecIndex) GetRootSecurityReferences() []*Reference

GetRootSecurityReferences will return all root security settings

func (*SpecIndex) GetRootServersNode 

func (index *SpecIndex) GetRootServersNode() *yaml.Node

GetRootServersNode will return the root servers node

func (*SpecIndex) GetSchemasNode 

func (index *SpecIndex) GetSchemasNode() *yaml.Node

GetSchemasNode will return the schema's node found in the spec

func (*SpecIndex) GetSecurityRequirementReferences added in v0.1.4 

func (index *SpecIndex) GetSecurityRequirementReferences() map[string]map[string][]*Reference

GetSecurityRequirementReferences will return all security requirement definitions found in the document

func (*SpecIndex) GetSpecAbsolutePath added in v0.13.0 

func (index *SpecIndex) GetSpecAbsolutePath() string

GetSpecAbsolutePath returns the absolute path to the spec file for the index. Will be absolute, either as a http link or a file.

func (*SpecIndex) GetTotalTagsCount 

func (index *SpecIndex) GetTotalTagsCount() int

GetTotalTagsCount will return the number of global and operation tags found that are unique.

func (*SpecIndex) MapNodes added in v0.13.12 

func (index *SpecIndex) MapNodes(rootNode *yaml.Node)

MapNodes maps all nodes in the document to a map of line/column to node.

func (*SpecIndex) SearchIndexForReference added in v0.6.0 

func (index *SpecIndex) SearchIndexForReference(ref string) (*Reference, *SpecIndex)

SearchIndexForReference searches the index for a reference, first looking through the mapped references and then externalSpecIndex for a match. If no match is found, it will recursively search the child indexes extracted when parsing the OpenAPI Spec.

func (*SpecIndex) SearchIndexForReferenceByReference added in v0.13.0 

func (index *SpecIndex) SearchIndexForReferenceByReference(fullRef *Reference) (*Reference, *SpecIndex)

func (*SpecIndex) SearchIndexForReferenceByReferenceWithContext added in v0.13.0 

func (index *SpecIndex) SearchIndexForReferenceByReferenceWithContext(ctx context.Context, searchRef *Reference) (*Reference, *SpecIndex, context.Context)

func (*SpecIndex) SearchIndexForReferenceWithContext added in v0.13.0 

func (index *SpecIndex) SearchIndexForReferenceWithContext(ctx context.Context, ref string) (*Reference, *SpecIndex, context.Context)

func (*SpecIndex) SetAbsolutePath added in v0.13.12 

func (index *SpecIndex) SetAbsolutePath(absolutePath string)

SetAbsolutePath sets the absolute path to the spec file for the index. Will be absolute, either as a http link or a file.

func (*SpecIndex) SetAllowCircularReferenceResolving added in v0.0.5 

func (index *SpecIndex) SetAllowCircularReferenceResolving(allow bool)

SetAllowCircularReferenceResolving will flip a bit that can be used by any consumers to determine if they want to allow or disallow circular references to be resolved or visited

func (*SpecIndex) SetCache added in v0.13.0 

func (index *SpecIndex) SetCache(sync *syncmap.Map)

func (*SpecIndex) SetCircularReferences added in v0.0.5 

func (index *SpecIndex) SetCircularReferences(refs []*CircularReferenceResult)

SetCircularReferences is a convenience method for the resolver to pass in circular references if the resolver is used.

func (*SpecIndex) SetIgnoredArrayCircularReferences added in v0.15.0 

func (index *SpecIndex) SetIgnoredArrayCircularReferences(refs []*CircularReferenceResult)

func (*SpecIndex) SetIgnoredPolymorphicCircularReferences added in v0.15.0 

func (index *SpecIndex) SetIgnoredPolymorphicCircularReferences(refs []*CircularReferenceResult)

SetIgnoredPolymorphicCircularReferences passes on any ignored poly circular refs captured using `IgnorePolymorphicCircularReferences`

type SpecIndexConfig added in v0.6.0 

type SpecIndexConfig struct {
	// The BaseURL will be the root from which relative references will be resolved from if they can't be found locally.
	//
	// For example:
	//  - $ref: somefile.yaml#/components/schemas/SomeSchema
	//
	// Might not be found locally, if the file was pulled in from a remote server (a good example is the DigitalOcean API).
	// so by setting a BaseURL, the reference will try to be resolved from the remote server.
	//
	// If our baseURL is set to https://pb33f.io/libopenapi then our reference will try to be resolved from:
	//  - $ref: https://pb33f.io/libopenapi/somefile.yaml#/components/schemas/SomeSchema
	//
	// More details on relative references can be found in issue #73: https://github.com/pb33f/libopenapi/issues/73
	BaseURL *url.URL // set the Base URL for resolving relative references if the spec is exploded.

	// If resolving remotely, the RemoteURLHandler will be used to fetch the remote document.
	// If not set, the default http client will be used.
	// Resolves [#132]: https://github.com/pb33f/libopenapi/issues/132
	// deprecated: Use the Rolodex instead
	RemoteURLHandler func(url string) (*http.Response, error)

	// FSHandler is an entity that implements the `fs.FS` interface that will be used to fetch local or remote documents.
	// This is useful if you want to use a custom file system handler, or if you want to use a custom http client or
	// custom network implementation for a lookup.
	//
	// libopenapi will pass the path to the FSHandler, and it will be up to the handler to determine how to fetch
	// the document. This is really useful if your application has a custom file system or uses a database for storing
	// documents.
	//
	// Is the FSHandler is set, it will be used for all lookups, regardless of whether they are local or remote.
	// it also overrides the RemoteURLHandler if set.
	//
	// Resolves[#85] https://github.com/pb33f/libopenapi/issues/85
	// deprecated: Use the Rolodex instead
	FSHandler fs.FS

	// If resolving locally, the BasePath will be the root from which relative references will be resolved from
	BasePath string // set the Base Path for resolving relative references if the spec is exploded.

	// In an earlier version of libopenapi (pre 0.6.0) the index would automatically resolve all references
	// They could have been local, or they could have been remote. This was a problem because it meant
	// There was a potential for a remote exploit if a remote reference was malicious. There aren't any known
	// exploits, but it's better to be safe than sorry.
	//
	// To read more about this, you can find a discussion here: https://github.com/pb33f/libopenapi/pull/64
	AllowRemoteLookup bool // Allow remote lookups for references. Defaults to false
	AllowFileLookup   bool // Allow file lookups for references. Defaults to false

	// If set to true, the index will not be built out, which means only the foundational elements will be
	// parsed and added to the index. This is useful to avoid building out an index if the specification is
	// broken up into references and want it fully resolved.
	//
	// Use the `BuildIndex()` method on the index to build it out once resolved/ready.
	AvoidBuildIndex bool

	// If set to true, the index will not check for circular references automatically, this should be triggered
	// manually, otherwise resolving may explode.
	AvoidCircularReferenceCheck bool

	// Logger is a logger that will be used for logging errors and warnings. If not set, the default logger
	// will be used, set to the Error level.
	Logger *slog.Logger

	// SpecInfo is a pointer to the SpecInfo struct that contains the root node and the spec version. It's the
	// struct that was used to create this index.
	SpecInfo *datamodel.SpecInfo

	// Rolodex is what provides all file and remote based lookups. Without the rolodex, no remote or file lookups
	// can be used. Normally you won't need to worry about setting this as each root document gets a rolodex
	// of its own automatically.
	Rolodex *Rolodex

	// The absolute path to the spec file for the index. Will be absolute, either as a http link or a file.
	// If the index is for a single file spec, then the root will be empty.
	SpecAbsolutePath string

	// IgnorePolymorphicCircularReferences will skip over checking for circular references in polymorphic schemas.
	// A polymorphic schema is any schema that is composed other schemas using references via `oneOf`, `anyOf` of `allOf`.
	// This is disabled by default, which means polymorphic circular references will be checked.
	IgnorePolymorphicCircularReferences bool

	// IgnoreArrayCircularReferences will skip over checking for circular references in arrays. Sometimes a circular
	// reference is required to describe a data-shape correctly. Often those shapes are valid circles if the
	// type of the schema implementing the loop is an array. An empty array would technically break the loop.
	// So if libopenapi is returning circular references for this use case, then this option should be enabled.
	// this is disabled by default, which means array circular references will be checked.
	IgnoreArrayCircularReferences bool

	// SkipDocumentCheck will skip the document check when building the index. A document check will look for an 'openapi'
	// or 'swagger' node in the root of the document. If it's not found, then the document is not a valid OpenAPI or
	// the file is a JSON Schema. To allow JSON Schema files to be included set this to true.
	SkipDocumentCheck bool

	// ExtractRefsSequentially will extract all references sequentially, which means the index will look up references
	// as it finds them, vs looking up everything asynchronously.
	// This is a more thorough way of building the index, but it's slower. It's required building a document
	// to be bundled.
	ExtractRefsSequentially bool
	// contains filtered or unexported fields
}

SpecIndexConfig is a configuration struct for the SpecIndex introduced in 0.6.0 that provides an expandable set of granular options. The first being the ability to set the Base URL for resolving relative references, and allowing or disallowing remote or local file lookups.

func CreateClosedAPIIndexConfig added in v0.6.0 

func CreateClosedAPIIndexConfig() *SpecIndexConfig

CreateClosedAPIIndexConfig is a helper function to create a new SpecIndexConfig with the AllowRemoteLookup and AllowFileLookup set to false. This is the default behaviour of the index in versions 0.6.0+

The default BasePath is the current working directory.

func CreateOpenAPIIndexConfig added in v0.6.0 

func CreateOpenAPIIndexConfig() *SpecIndexConfig

CreateOpenAPIIndexConfig is a helper function to create a new SpecIndexConfig with the AllowRemoteLookup and AllowFileLookup set to true. This is the default behaviour of the index in previous versions of libopenapi. (pre 0.6.0)

The default BasePath is the current working directory.

Source Files

View all Source files

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.