index

package
v0.2.8 Latest Latest
Warning

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

 Go to latest Published: Nov 30, 2022 License: MIT Imports: 9 Imported by: 19

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

View Source 
const (
	LocalResolve = iota
	HttpResolve
	FileResolve
)

Constants used to determine if resolving is local, file based or remote file based.

Variables

This section is empty.

Functions

func DetermineReferenceResolveType added in v0.0.5 

func DetermineReferenceResolveType(ref string) int

Types

type CircularReferenceResult 

type CircularReferenceResult struct {
	Journey             []*Reference
	Start               *Reference
	LoopIndex           int
	LoopPoint           *Reference
	IsPolymorphicResult bool // if this result comes from a polymorphic loop.
}

CircularReferenceResult contains a circular reference found when traversing the graph.

func (*CircularReferenceResult) GenerateJourneyPath added in v0.0.5 

func (c *CircularReferenceResult) GenerateJourneyPath() string

type DescriptionReference 

type DescriptionReference struct {
	Content   string
	Path      string
	Node      *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
	Type *yaml.Node
	Path string
}

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 IndexingError 

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

IndexingError holds data about something that went wrong during indexing.

type Reference 

type Reference struct {
	Definition     string
	Name           string
	Node           *yaml.Node
	ParentNode     *yaml.Node
	Resolved       bool
	Circular       bool
	Seen           bool
	IsRemote       bool
	RemoteLocation string
	Path           string // this won't always be available.
}

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.

type ReferenceMapped 

type ReferenceMapped struct {
	Reference  *Reference
	Definition string
}

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

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.

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, _ := ioutil.ReadFile("../test_specs/stripe.yaml")

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

// create a new specification index.
index := NewSpecIndex(&rootNode)

// print out some statistics
fmt.Printf("There are %d references\n"+
	"%d paths\n"+
	"%d operations\n"+
	"%d schemas\n"+
	"%d enums\n"+
	"%d polymorphic references",
	len(index.GetAllCombinedReferences()),
	len(index.GetAllPaths()),
	index.GetOperationCount(),
	len(index.GetAllSchemas()),
	len(index.GetAllEnums()),
	len(index.GetPolyOneOfReferences())+len(index.GetPolyAnyOfReferences()))

Output:

There are 537 references
246 paths
402 operations
537 schemas
1516 enums
828 polymorphic references

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) 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, parent *yaml.Node) *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) 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) 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) GetAllExternalIndexes added in v0.0.5 

func (index *SpecIndex) GetAllExternalIndexes() map[string]*SpecIndex

GetAllExternalIndexes will return all indexes for external documents

func (*SpecIndex) GetAllHeaders 

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

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

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

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

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) 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() map[string]*Reference

GetAllSchemas will return all schemas found in the document

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) 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) 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 node.

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

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) GetReferenceIndexErrors added in v0.0.5 

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

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

func (index *SpecIndex) GetTotalTagsCount() int

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

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

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.