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
• type DocumentConfiguration
  • func NewClosedDocumentConfiguration() *DocumentConfiguration
  • func NewOpenDocumentConfiguration() *DocumentConfiguration
• 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 (si SpecInfo) GetJSONParsingChannel() chan bool

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

Types

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.
	// Resolves [#132]: https://github.com/pb33f/libopenapi/issues/132
	RemoteURLHandler func(url string) (*http.Response, error)

	// 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.
	BasePath string // set the Base Path for resolving relative references if the spec is exploded.

	// AllowFileReferences will allow the index to locate relative file references. This is disabled by default.
	AllowFileReferences bool

	// AllowRemoteReferences will allow the index to lookup remote references. This is disabled by default.
	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
}

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 NewClosedDocumentConfiguration

func NewClosedDocumentConfiguration() *DocumentConfiguration

func NewOpenDocumentConfiguration

func NewOpenDocumentConfiguration() *DocumentConfiguration

type SpecInfo

type SpecInfo struct {
	SpecType            string                  `json:"type"`
	Version             string                  `json:"version"`
	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:"-"`
	JsonParsingChannel  chan bool               `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, _ := ioutil.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)

func (SpecInfo) GetJSONParsingChannel

func (si SpecInfo) GetJSONParsingChannel() chan bool

GetJSONParsingChannel returns a channel that will close once async JSON parsing is completed. This is really useful if your application wants to analyze the JSON via SpecJSON. the library will return *SpecInfo BEFORE the JSON is done parsing, so things are as fast as possible.

If you want to know when parsing is done, listen on the channel for a bool.