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 SpecInfo
  • func ExtractSpecInfo(spec []byte) (*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 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:"-"`
}

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