datamodel

Documentation

Overview

Package datamodel contains two sets of models, high and low.

The low level (or plumbing) models are designed to capture every single detail about specification, including all lines, columns, positions, tags, comments and essentially everything you would ever want to know. Positions of every key, value and meta-data that is lost when blindly un-marshaling JSON/YAML into a struct.

The high model (porcelain) is a much simpler representation of the low model, keys are simple strings and indices are numbers. When developing consumers of the model, the high model is really what you want to use instead of the low model, it's much easier to navigate and is designed for easy consumption.

The high model requires the low model to be built. Every high model has a 'GoLow' method that allows the consumer to 'drop down' from the porcelain API to the plumbing API, which gives instant access to everything low.

Index

• Constants
• Variables
• func TranslateMapParallel[K comparable, V any, RV any](m *orderedmap.Map[K, V], translate TranslateFunc[orderedmap.Pair[K, V], RV], ...) error
• func TranslatePipeline[IN any, OUT any](in <-chan IN, out chan<- OUT, translate TranslateFunc[IN, OUT]) error
• func TranslateSliceParallel[IN any, OUT any](in []IN, translate TranslateSliceFunc[IN, OUT], result ActionFunc[OUT]) error
• type ActionFunc
• type DocumentConfiguration
  • func NewDocumentConfiguration() *DocumentConfiguration
• type ResultFunc
• type SpecInfo
  • func ExtractSpecInfo(spec []byte) (*SpecInfo, error)
  • func ExtractSpecInfoWithConfig(spec []byte, config *DocumentConfiguration) (*SpecInfo, error)
  • func ExtractSpecInfoWithDocumentCheck(spec []byte, bypass bool) (*SpecInfo, error)
  • func ExtractSpecInfoWithDocumentCheckSync(spec []byte, bypass bool) (*SpecInfo, error)
• type TranslateFunc
• type TranslateMapFunc
• type TranslateSliceFunc

Examples

• ExtractSpecInfo

Constants

const (
	// OAS2 represents Swagger Documents
	OAS2 = "oas2"

	// OAS3 represents OpenAPI 3.0+ Documents
	OAS3 = "oas3"

	// OAS31 represents OpenAPI 3.1+ Documents
	OAS31 = "oas3_1"
)

Constants used by utilities to determine the version of OpenAPI that we're referring to.

const (
	JSONFileType = "json"
	YAMLFileType = "yaml"
)

Variables

var AllFormats = []string{OAS3, OAS31, OAS2}

AllFormats defines all versions of OpenAPI

var Continue = &continueError{error: errors.New("Continue")}

var OAS2Format = []string{OAS2}

OAS2Format defines documents that compose swagger documnets (version 2.0)

var OAS3AllFormat = []string{OAS3, OAS31}

OAS3AllFormat defines documents that compose all 3+ versions

var OAS3Format = []string{OAS3}

OAS3Format defines documents that can only be version 3.0

var OAS3_1Format = []string{OAS31}

OAS3_1Format defines documents that can only be version 3.1

var OpenAPI2SchemaData string // embedded OAS3 schema

OpenAPI2SchemaData is an embedded version of the OpenAPI 2 (Swagger) Schema

var OpenAPI31SchemaData string // embedded OAS31 schema

OpenAPI31SchemaData is an embedded version of the OpenAPI 3.1 Schema

var OpenAPI3SchemaData string // embedded OAS3 schema

OpenAPI3SchemaData is an embedded version of the OpenAPI 3 Schema

Functions

func TranslateMapParallel

func TranslateMapParallel[K comparable, V any, RV any](m *orderedmap.Map[K, V], translate TranslateFunc[orderedmap.Pair[K, V], RV], result ResultFunc[RV]) error

TranslateMapParallel iterates a `*orderedmap.Map` in parallel and calls translate() asynchronously. translate() or result() may return `io.EOF` to break iteration. Safely handles nil pointer. Results are provided sequentially to result() in stable order from `*orderedmap.Map`.

func TranslatePipeline

func TranslatePipeline[IN any, OUT any](in <-chan IN, out chan<- OUT, translate TranslateFunc[IN, OUT]) error

TranslatePipeline processes input sequentially through predicate(), sends to translate() in parallel, then outputs in stable order. translate() may return `datamodel.Continue` to continue iteration. Caller must close `in` channel to indicate EOF. TranslatePipeline closes `out` channel to indicate EOF.

func TranslateSliceParallel

func TranslateSliceParallel[IN any, OUT any](in []IN, translate TranslateSliceFunc[IN, OUT], result ActionFunc[OUT]) error

TranslateSliceParallel iterates a slice in parallel and calls translate() asynchronously. translate() may return `datamodel.Continue` to continue iteration. translate() or result() may return `io.EOF` to break iteration. Results are provided sequentially to result() in stable order from slice.

Types

type ActionFunc

type ActionFunc[T any] func(T) error

type DocumentConfiguration

type DocumentConfiguration struct {
	// The BaseURL will be the root from which relative references will be resolved from if they can't be found locally.
	// Schema must be set to "http/https".
	BaseURL *url.URL

	// RemoteURLHandler is a function that will be used to retrieve remote documents. If not set, the default
	// remote document getter will be used.
	//
	// The remote handler is only used if the BaseURL is set. If the BaseURL is not set, then the remote handler
	// will not be used, as there will be nothing to use it against.
	//
	// Resolves [#132]: https://github.com/pb33f/libopenapi/issues/132
	RemoteURLHandler utils.RemoteURLHandler

	// If resolving locally, the BasePath will be the root from which relative references will be resolved from.
	// It's usually the location of the root specification.
	//
	// Be warned, setting this value will instruct the rolodex to index EVERY yaml and JSON file it finds from the
	// base path. The rolodex will recurse into every directory and pick up everything form this location down.
	//
	// To avoid sucking in all the files, set the FileFilter to a list of specific files to be included.
	BasePath string // set the Base Path for resolving relative references if the spec is exploded.

	// FileFilter is a list of specific files to be included by the rolodex when looking up references. If this value
	// is set, then only these specific files will be included. If this value is not set, then all files will be included.
	FileFilter []string

	// RemoteFS is a filesystem that will be used to retrieve remote documents. If not set, then the rolodex will
	// use its own internal remote filesystem implementation. The RemoteURLHandler will be used to retrieve remote
	// documents if it has been set. The default is to use the internal remote filesystem loader.
	RemoteFS fs.FS

	// LocalFS is a filesystem that will be used to retrieve local documents. If not set, then the rolodex will
	// use its own internal local filesystem implementation. The default is to use the internal local filesystem loader.
	LocalFS fs.FS

	// AllowFileReferences will allow the index to locate relative file references. This is disabled by default.
	//
	// This behavior is now driven by the inclusion of a BasePath. If a BasePath is set, then the
	// rolodex will look for relative file references. If no BasePath is set, then the rolodex will not look for
	// relative file references.
	//
	// This value when set, will force the creation of a local file system even when the BasePath has not been set.
	// it will suck in and index everything from the current working directory, down... so be warned
	// FileFilter should be used to limit the scope of the rolodex.
	AllowFileReferences bool

	// AllowRemoteReferences will allow the index to lookup remote references. This is disabled by default.
	//
	// This behavior is now driven by the inclusion of a BaseURL. If a BaseURL is set, then the
	// rolodex will look for remote references. If no BaseURL is set, then the rolodex will not look for
	// remote references. This value has no effect as of version 0.13.0 and will be removed in a future release.
	//
	// This value when set, will force the creation of a remote file system even when the BaseURL has not been set.
	// it will suck in every http link it finds, and recurse through all references located in each document.
	AllowRemoteReferences bool

	// AvoidIndexBuild will avoid building the index. This is disabled by default, only use if you are sure you don't need it.
	// This is useful for developers building out models that should be indexed later on.
	AvoidIndexBuild bool

	// BypassDocumentCheck will bypass the document check. This is disabled by default. This will allow any document to
	// passed in and used. Only enable this when parsing non openapi documents.
	BypassDocumentCheck bool

	// 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

	// SkipCircularReferenceCheck will skip over checking for circular references. This is disabled by default, which
	// means circular references will be checked. This is useful for developers building out models that should be
	// indexed later on.
	SkipCircularReferenceCheck bool

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

	// 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

	// BundleInlineRefs is used by the bundler module. If set to true, all references will be inlined, including
	// local references (to the root document) as well as all external references. This is false by default.
	BundleInlineRefs bool
}

DocumentConfiguration is used to configure the document creation process. It was added in v0.6.0 to allow for more fine-grained control over controls and new features.

The default configuration will set AllowFileReferences to false and AllowRemoteReferences to false, which means any non-local (local being the specification, not the file system) references, will be ignored.

func NewDocumentConfiguration

func NewDocumentConfiguration() *DocumentConfiguration

type ResultFunc

type ResultFunc[V any] func(V) error

type SpecInfo

type SpecInfo struct {
	SpecType            string                  `json:"type"`
	NumLines            int                     `json:"numLines"`
	Version             string                  `json:"version"`
	VersionNumeric      float32                 `json:"versionNumeric"`
	SpecFormat          string                  `json:"format"`
	SpecFileType        string                  `json:"fileType"`
	SpecBytes           *[]byte                 `json:"bytes"` // the original byte array
	RootNode            *yaml.Node              `json:"-"`     // reference to the root node of the spec.
	SpecJSONBytes       *[]byte                 `json:"-"`     // original bytes converted to JSON
	SpecJSON            *map[string]interface{} `json:"-"`     // standard JSON map of original bytes
	Error               error                   `json:"-"`     // something go wrong?
	APISchema           string                  `json:"-"`     // API Schema for supplied spec type (2 or 3)
	Generated           time.Time               `json:"-"`
	OriginalIndentation int                     `json:"-"` // the original whitespace
}

SpecInfo represents a 'ready-to-process' OpenAPI Document. The RootNode is the most important property used by the library, this contains the top of the document tree that every single low model is based off.

func ExtractSpecInfo

func ExtractSpecInfo(spec []byte) (*SpecInfo, error)

ExtractSpecInfo accepts an OpenAPI/Swagger specification that has been read into a byte array and will return a SpecInfo pointer, which contains details on the version and an un-marshaled *yaml.Node root node tree. The root node tree is what's used by the library when building out models.

If the spec cannot be parsed correctly then an error will be returned, otherwise the error is nil.

Example

// load bytes from openapi spec file.
bytes, _ := os.ReadFile("../test_specs/petstorev3.json")

// create a new *SpecInfo instance from loaded bytes
specInfo, err := ExtractSpecInfo(bytes)
if err != nil {
	panic(fmt.Sprintf("cannot extract spec info: %e", err))
}

// print out the version, format and filetype
fmt.Printf("the version of the spec is %s, the format is %s and the file type is %s",
	specInfo.Version, specInfo.SpecFormat, specInfo.SpecFileType)

Output:

the version of the spec is 3.0.2, the format is oas3 and the file type is json

func ExtractSpecInfoWithConfig

func ExtractSpecInfoWithConfig(spec []byte, config *DocumentConfiguration) (*SpecInfo, error)

func ExtractSpecInfoWithDocumentCheck

func ExtractSpecInfoWithDocumentCheck(spec []byte, bypass bool) (*SpecInfo, error)

ExtractSpecInfoWithDocumentCheck accepts an OpenAPI/Swagger specification that has been read into a byte array and will return a SpecInfo pointer, which contains details on the version and an un-marshaled ensures the document is an OpenAPI document.

func ExtractSpecInfoWithDocumentCheckSync

func ExtractSpecInfoWithDocumentCheckSync(spec []byte, bypass bool) (*SpecInfo, error)

ExtractSpecInfoWithDocumentCheckSync accepts an OpenAPI/Swagger specification that has been read into a byte array and will return a SpecInfo pointer, which contains details on the version and an un-marshaled deprecated: use ExtractSpecInfoWithDocumentCheck instead, this function will be removed in a later version.

type TranslateFunc

type TranslateFunc[IN any, OUT any] func(IN) (OUT, error)

type TranslateMapFunc

type TranslateMapFunc[IN any, OUT any] func(IN) (OUT, error)

type TranslateSliceFunc

type TranslateSliceFunc[IN any, OUT any] func(int, IN) (OUT, error)