index

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: 23 Imported by: 1

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 

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

func HumanFileSize 

func HumanFileSize(size float64) string

func Round 

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

Types

type CanBeIndexed 

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 

func (c *CircularReferenceResult) GenerateJourneyPath() string

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

type ContextKey 

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 

type ExtractedRef struct {
	Location string
	Type     RefType
}

func (*ExtractedRef) GetFile 

func (r *ExtractedRef) GetFile() string

GetFile returns the file path of the reference.

func (*ExtractedRef) GetReference 

func (r *ExtractedRef) GetReference() string

GetReference returns the reference path of the reference.

type FileExtension 

type FileExtension int

FileExtension is the type of file extension. 

const (
	YAML FileExtension = iota
	JSON
	UNSUPPORTED
)

func ExtractFileType 

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 

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

LocalFS is a file system that indexes local files.

func NewLocalFSWithConfig 

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

NewLocalFSWithConfig creates a new LocalFS with the supplied configuration.

func (*LocalFS) GetErrors 

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

GetErrors returns any errors that occurred during the indexing process.

func (*LocalFS) GetFiles 

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 

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 

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 

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 

func (l *LocalFile) Close() error

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

func (*LocalFile) FullPath 

func (l *LocalFile) FullPath() string

FullPath returns the full path of the file.

func (*LocalFile) GetContent 

func (l *LocalFile) GetContent() string

GetContent returns the content of the file as a string.

func (*LocalFile) GetContentAsYAMLNode 

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 

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

GetErrors returns any errors that occurred during the indexing process.

func (*LocalFile) GetFileExtension 

func (l *LocalFile) GetFileExtension() FileExtension

GetFileExtension returns the FileExtension of the file.

func (*LocalFile) GetFullPath 

func (l *LocalFile) GetFullPath() string

GetFullPath returns the full path of the file.

func (*LocalFile) GetIndex 

func (l *LocalFile) GetIndex() *SpecIndex

GetIndex returns the *SpecIndex for the file.

func (*LocalFile) Index 

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 

func (l *LocalFile) IsDir() bool

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

func (*LocalFile) ModTime 

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

ModTime returns the modification time of the file.

func (*LocalFile) Mode 

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

Mode returns the file mode bits for the file.

func (*LocalFile) Name 

func (l *LocalFile) Name() string

Name returns the name of the file.

func (*LocalFile) Read 

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 

func (l *LocalFile) Size() int64

Size returns the size of the file.

func (*LocalFile) Stat 

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

Stat returns the FileInfo for the file.

func (*LocalFile) Sys 

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

Sys returns the underlying data source (always returns nil)

type NodeOrigin 

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 

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

type RefType 

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 

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 

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 

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

NewRemoteFSWithConfig creates a new RemoteFS using the supplied SpecIndexConfig.

func NewRemoteFSWithRootURL 

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

NewRemoteFSWithRootURL creates a new RemoteFS using the supplied root URL.

func (*RemoteFS) GetErrors 

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

GetErrors returns any errors that occurred during the indexing process.

func (*RemoteFS) GetFiles 

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

GetFiles returns the files that have been indexed.

func (*RemoteFS) Open 

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 

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

SetIndexConfig sets the index configuration.

func (*RemoteFS) SetRemoteHandlerFunc 

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

SetRemoteHandlerFunc sets the remote handler function.

type RemoteFile 

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 

func (f *RemoteFile) Close() error

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

func (*RemoteFile) GetContent 

func (f *RemoteFile) GetContent() string

GetContent returns the content of the file as a string.

func (*RemoteFile) GetContentAsYAMLNode 

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

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

func (*RemoteFile) GetErrors 

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

GetErrors returns any errors that occurred while reading the file.

func (*RemoteFile) GetFileExtension 

func (f *RemoteFile) GetFileExtension() FileExtension

GetFileExtension returns the file extension of the file.

func (*RemoteFile) GetFileName 

func (f *RemoteFile) GetFileName() string

GetFileName returns the name of the file.

func (*RemoteFile) GetFullPath 

func (f *RemoteFile) GetFullPath() string

GetFullPath returns the full path of the file.

func (*RemoteFile) GetIndex 

func (f *RemoteFile) GetIndex() *SpecIndex

GetIndex returns the index for the file.

func (*RemoteFile) GetLastModified 

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

GetLastModified returns the last modified time of the file.

func (*RemoteFile) Index 

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 

func (f *RemoteFile) IsDir() bool

IsDir returns true if the file is a directory.

func (*RemoteFile) ModTime 

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

ModTime returns the modification time of the file.

func (*RemoteFile) Mode 

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

Mode returns the file mode bits for the file.

func (*RemoteFile) Name 

func (f *RemoteFile) Name() string

Name returns the name of the file.

func (*RemoteFile) Read 

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

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

func (*RemoteFile) Size 

func (f *RemoteFile) Size() int64

Size returns the size of the file.

func (*RemoteFile) Stat 

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

Stat returns the FileInfo for the file.

func (*RemoteFile) Sys 

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

Sys returns the underlying data source (always returns nil)

type Resolver 

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 

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 

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

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

func (*Resolver) GetCircularReferences 

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

func (*Resolver) GetIgnoredCircularArrayReferences 

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

GetIgnoredCircularArrayReferences returns all ignored circular references that are arrays

func (*Resolver) GetIgnoredCircularPolyReferences 

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

GetIgnoredCircularPolyReferences returns all ignored circular references that are polymorphic

func (*Resolver) GetIndexesVisited 

func (resolver *Resolver) GetIndexesVisited() int

GetIndexesVisited returns the number of indexes visited by the resolver

func (*Resolver) GetInfiniteCircularReferences 

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

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

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() []*CircularReferenceResult

GetNonPolymorphicCircularErrors returns all circular errors that DO NOT stem from polymorphism

func (*Resolver) GetPolymorphicCircularErrors 

func (resolver *Resolver) GetPolymorphicCircularErrors() []*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) GetSafeCircularReferences 

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

GetSafeCircularReferences returns all circular reference errors found.

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) ResolvePendingNodes 

func (resolver *Resolver) ResolvePendingNodes()

func (*Resolver) VisitReference 

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 

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 

func (r *ResolvingError) Error() string

type Rolodex 

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 

func NewRolodex(indexConfig *SpecIndexConfig) *Rolodex

NewRolodex creates a new rolodex with the provided index configuration.

func (*Rolodex) AddExternalIndex 

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

func (*Rolodex) AddIndex 

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

func (*Rolodex) AddLocalFS 

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

AddLocalFS adds a local file system to the rolodex.

func (*Rolodex) AddRemoteFS 

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

AddRemoteFS adds a remote file system to the rolodex.

func (*Rolodex) BuildIndexes 

func (r *Rolodex) BuildIndexes()

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

func (*Rolodex) CheckForCircularReferences 

func (r *Rolodex) CheckForCircularReferences()

CheckForCircularReferences checks for circular references in the rolodex.

func (*Rolodex) FindNodeOrigin 

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 

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

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

func (*Rolodex) GetIgnoredCircularReferences 

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 

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

GetIndexes returns all the indexes in the rolodex.

func (*Rolodex) GetIndexingDuration 

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

GetIndexingDuration returns the duration it took to index the rolodex.

func (*Rolodex) GetRootIndex 

func (r *Rolodex) GetRootIndex() *SpecIndex

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

func (*Rolodex) GetRootNode 

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

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

func (*Rolodex) IndexTheRolodex 

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 

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

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

func (*Rolodex) Resolve 

func (r *Rolodex) Resolve()

Resolve resolves references in the rolodex.

func (*Rolodex) RolodexFileSize 

func (r *Rolodex) RolodexFileSize() int64

func (*Rolodex) RolodexFileSizeAsString 

func (r *Rolodex) RolodexFileSizeAsString() string

func (*Rolodex) RolodexTotalFiles 

func (r *Rolodex) RolodexTotalFiles() int

func (*Rolodex) SetRootNode 

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

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

type RolodexFS 

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 

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 

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 

func (index *SpecIndex) AllowCircularReferenceResolving() bool

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

func (*SpecIndex) BuildIndex 

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 

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

func (*SpecIndex) FindNodeOrigin 

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 

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 

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 

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 

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 

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 

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

func (*SpecIndex) GetCircularReferences 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

func (index *SpecIndex) GetResolver() *Resolver

GetResolver returns the resolver for this index.

func (*SpecIndex) GetRolodex 

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 

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

GetSecurityRequirementReferences will return all security requirement definitions found in the document

func (*SpecIndex) GetSpecAbsolutePath 

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 

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 

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 

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

func (*SpecIndex) SearchIndexForReferenceByReferenceWithContext 

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

func (*SpecIndex) SearchIndexForReferenceWithContext 

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

func (*SpecIndex) SetAbsolutePath 

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 

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 

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

func (*SpecIndex) SetCircularReferences 

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 

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

func (*SpecIndex) SetIgnoredPolymorphicCircularReferences 

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

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

type SpecIndexConfig 

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://devniel93.io/libopenapi then our reference will try to be resolved from:
	//  - $ref: https://devniel93.io/libopenapi/somefile.yaml#/components/schemas/SomeSchema
	//
	// More details on relative references can be found in issue #73: https://github.com/devniel93/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/devniel93/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/devniel93/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/devniel93/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 

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 

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.