Documentation

Index

Constants

View Source
const StringType = "string"

StringType For identifying string types

Variables

View Source
var ArrayType = "array"

ArrayType const for array

View Source
var ObjectType = "object"

ObjectType const for object

Functions

func JSONMarshal

func JSONMarshal(t interface{}) ([]byte, error)

JSONMarshal allows the item to be correctly rendered to json

Types

type CompareSchemaFn

type CompareSchemaFn func(location DifferenceLocation, schema1, schema2 *spec.Schema)

CompareSchemaFn Fn spec for comparing schemas

type Compatibility

type Compatibility int

Compatibility - whether this is a breaking or non-breaking change

const (
	// Breaking this change could break existing clients
	Breaking Compatibility = iota
	// NonBreaking This is a backwards-compatible API change
	NonBreaking
)

func (Compatibility) MarshalJSON

func (s Compatibility) MarshalJSON() ([]byte, error)

MarshalJSON marshals the enum as a quoted json string

func (Compatibility) String

func (s Compatibility) String() string

func (*Compatibility) UnmarshalJSON

func (s *Compatibility) UnmarshalJSON(b []byte) error

UnmarshalJSON unmashals a quoted json string to the enum value

type CompatibilityPolicy

type CompatibilityPolicy struct {
	ForResponse map[SpecChangeCode]Compatibility
	ForRequest  map[SpecChangeCode]Compatibility
	ForChange   map[SpecChangeCode]Compatibility
}

CompatibilityPolicy decides which changes are breaking and which are not

type DataDirection

type DataDirection int

DataDirection indicates the direction of change Request vs Response

const (
	// Request Used for messages/param diffs in a request
	Request DataDirection = iota
	// Response Used for messages/param diffs in a response
	Response
)

type DifferenceLocation

type DifferenceLocation struct {
	URL      string `json:"url"`
	Method   string `json:"method,omitempty"`
	Response int    `json:"response,omitempty"`
	Node     *Node  `json:"node,omitempty"`
}

DifferenceLocation indicates where the difference occurs

func (DifferenceLocation) AddNode

func (dl DifferenceLocation) AddNode(node *Node) DifferenceLocation

AddNode returns a copy of this location with the leaf node added

type Node

type Node struct {
	Field     string `json:"name,omitempty"`
	TypeName  string `json:"type,omitempty"`
	IsArray   bool   `json:"is_array,omitempty"`
	ChildNode *Node  `json:"child,omitempty"`
}

Node is the position od a diff in a spec

func (*Node) AddLeafNode

func (n *Node) AddLeafNode(toAdd *Node) *Node

AddLeafNode Adds (recursive) a Child to the first non-nil child found

func (Node) Copy

func (n Node) Copy() *Node

Copy deep copy of this node and children

func (*Node) String

func (n *Node) String() string

String std string render

type OperationMap

type OperationMap map[string]*spec.Operation

OperationMap saves indexing operations in PathItems individually

type Pair

type Pair struct {
	First  interface{}
	Second interface{}
}

Pair stores a pair of items which share a key in two maps

type PathItemOp

type PathItemOp struct {
	ParentPathItem *spec.PathItem  `json:"pathitem"`
	Operation      *spec.Operation `json:"operation"`
}

PathItemOp - combines path and operation into a single keyed entity

type PropertyDefn

type PropertyDefn struct {
	Schema   *spec.Schema
	Required bool
}

PropertyDefn combines a property with its required-ness

type PropertyMap

type PropertyMap map[string]PropertyDefn

PropertyMap a unified map including all AllOf fields

type SchemaFromRefFn

type SchemaFromRefFn func(spec.Ref) (*spec.Schema, string)

SchemaFromRefFn define this to get a schema for a ref

type SpecAnalyser

type SpecAnalyser struct {
	Diffs SpecDifferences

	Definitions1          spec.Definitions
	Definitions2          spec.Definitions
	ReferencedDefinitions map[string]bool // contains filtered or unexported fields

}

SpecAnalyser contains all the differences for a Spec

func NewSpecAnalyser

func NewSpecAnalyser() *SpecAnalyser

NewSpecAnalyser returns an empty SpecDiffs

func (*SpecAnalyser) Analyse

func (sd *SpecAnalyser) Analyse(spec1, spec2 *spec.Swagger) error

Analyse the differences in two specs

func (*SpecAnalyser) AnalyseDefinitions

func (sd *SpecAnalyser) AnalyseDefinitions()

AnalyseDefinitions check for changes to defintion objects not referenced in any endpoint

func (*SpecAnalyser) CompareProps

func (sd *SpecAnalyser) CompareProps(type1, type2 *spec.SchemaProps) []TypeDiff

CompareProps computes type specific property diffs

type SpecChangeCode

type SpecChangeCode int

SpecChangeCode enumerates the various types of diffs from one spec to another

const (
	// NoChangeDetected - the specs have no changes
	NoChangeDetected SpecChangeCode = iota
	// DeletedProperty - A message property has been deleted in the new spec
	DeletedProperty
	// AddedProperty - A message property has been added in the new spec
	AddedProperty
	// AddedRequiredProperty - A required message property has been added in the new spec
	AddedRequiredProperty
	// DeletedOptionalParam - An endpoint parameter has been deleted in the new spec
	DeletedOptionalParam
	// ChangedDescripton - Changed a description
	ChangedDescripton
	// AddedDescripton - Added a description
	AddedDescripton
	// DeletedDescripton - Deleted a description
	DeletedDescripton
	// ChangedTag - Changed a tag
	ChangedTag
	// AddedTag - Added a tag
	AddedTag
	// DeletedTag - Deleted a tag
	DeletedTag
	// DeletedResponse - An endpoint response has been deleted in the new spec
	DeletedResponse
	// DeletedEndpoint - An endpoint has been deleted in the new spec
	DeletedEndpoint
	// DeletedDeprecatedEndpoint - A deprecated endpoint has been deleted in the new spec
	DeletedDeprecatedEndpoint
	// AddedRequiredParam - A required parameter has been added in the new spec
	AddedRequiredParam
	// DeletedRequiredParam - A required parameter has been deleted in the new spec
	DeletedRequiredParam
	// AddedEndpoint - An endpoint has been added in the new spec
	AddedEndpoint
	// WidenedType - An type has been changed to a more permissive type eg int->string
	WidenedType
	// NarrowedType - An type has been changed to a less permissive type eg string->int
	NarrowedType
	// ChangedToCompatibleType - An type has been changed to a compatible type eg password->string
	ChangedToCompatibleType
	// ChangedType - An type has been changed to a type whose relative compatibility cannot be determined
	ChangedType
	// AddedEnumValue - An enum type has had a new potential value added to it
	AddedEnumValue
	// DeletedEnumValue - An enum type has had a existing value removed from it
	DeletedEnumValue
	// AddedOptionalParam - A new optional parameter has been added to the new spec
	AddedOptionalParam
	// ChangedOptionalToRequired - An optional parameter is now required in the new spec
	ChangedOptionalToRequired
	// ChangedRequiredToOptional - An required parameter is now optional in the new spec
	ChangedRequiredToOptional
	// AddedResponse An endpoint has new response code in the new spec
	AddedResponse
	// AddedConsumesFormat - a new consumes format (json/xml/yaml etc) has been added in the new spec
	AddedConsumesFormat
	// DeletedConsumesFormat - an existing format has been removed in the new spec
	DeletedConsumesFormat
	// AddedProducesFormat - a new produces format (json/xml/yaml etc) has been added in the new spec
	AddedProducesFormat
	// DeletedProducesFormat - an existing produces format has been removed in the new spec
	DeletedProducesFormat
	// AddedSchemes - a new scheme has been added to the new spec
	AddedSchemes
	// DeletedSchemes - a scheme has been removed from the new spec
	DeletedSchemes
	// ChangedHostURL - the host url has been changed. If this is used in the client generation, then clients will break.
	ChangedHostURL
	// ChangedBasePath - the host base path has been changed. If this is used in the client generation, then clients will break.
	ChangedBasePath
	// AddedResponseHeader Added a header Item
	AddedResponseHeader
	// ChangedResponseHeader Added a header Item
	ChangedResponseHeader
	// DeletedResponseHeader Added a header Item
	DeletedResponseHeader
	// RefTargetChanged Changed a ref to point to a different object
	RefTargetChanged
	// RefTargetRenamed Renamed a ref to point to the same object
	RefTargetRenamed
	// DeletedConstraint Deleted a schema constraint
	DeletedConstraint
	// AddedConstraint Added a schema constraint
	AddedConstraint
	// DeletedDefinition removed one of the definitions
	DeletedDefinition
	// AddedDefinition removed one of the definitions
	AddedDefinition
)

func (SpecChangeCode) Description

func (s SpecChangeCode) Description() (result string)

Description returns an english version of this error

func (SpecChangeCode) MarshalJSON

func (s SpecChangeCode) MarshalJSON() ([]byte, error)

MarshalJSON marshals the enum as a quoted json string

func (*SpecChangeCode) UnmarshalJSON

func (s *SpecChangeCode) UnmarshalJSON(b []byte) error

UnmarshalJSON unmashalls a quoted json string to the enum value

type SpecDifference

type SpecDifference struct {
	DifferenceLocation DifferenceLocation `json:"location"`
	Code               SpecChangeCode     `json:"code"`
	Compatibility      Compatibility      `json:"compatibility"`
	DiffInfo           string             `json:"info,omitempty"`
}

SpecDifference encapsulates the details of an individual diff in part of a spec

func CompareProperties

func CompareProperties(location DifferenceLocation, schema1 *spec.Schema, schema2 *spec.Schema, getRefFn1 SchemaFromRefFn, getRefFn2 SchemaFromRefFn, cmp CompareSchemaFn) []SpecDifference

CompareProperties recursive property comparison

func (SpecDifference) Matches

func (sd SpecDifference) Matches(other SpecDifference) bool

Matches returns true if the diff matches another

func (SpecDifference) String

func (sd SpecDifference) String() string

String std string renderer

type SpecDifferences

type SpecDifferences []SpecDifference

SpecDifferences list of differences

func Compare

func Compare(spec1, spec2 *spec.Swagger) (diffs SpecDifferences, err error)

Compare returns the result of analysing breaking and non breaking changes between to Swagger specs

func (SpecDifferences) BreakingChangeCount

func (sd SpecDifferences) BreakingChangeCount() int

BreakingChangeCount Calculates the breaking change count

func (SpecDifferences) Contains

func (sd SpecDifferences) Contains(diff SpecDifference) bool

Contains Returns true if the item contains the specified item

func (SpecDifferences) FilterIgnores

func (sd SpecDifferences) FilterIgnores(ignores SpecDifferences) SpecDifferences

FilterIgnores returns a copy of the list without the items in the specified ignore list

func (SpecDifferences) ReportAllDiffs

func (sd SpecDifferences) ReportAllDiffs(fmtJSON bool) (io.Reader, error, error)

ReportAllDiffs lists all the diffs between two specs

func (*SpecDifferences) ReportCompatibility

func (sd *SpecDifferences) ReportCompatibility() (io.Reader, error, error)

ReportCompatibility lists and spec

type TypeDiff

type TypeDiff struct {
	Change      SpecChangeCode `json:"change-type,omitempty"`
	Description string         `json:"description,omitempty"`
	FromType    string         `json:"from-type,omitempty"`
	ToType      string         `json:"to-type,omitempty"`
}

TypeDiff - describes a primitive type change

func CheckRefChange

func CheckRefChange(diffs []TypeDiff, type1, type2 interface{}) (diffReturn []TypeDiff)

CheckRefChange has the property ref changed

func CheckStringTypeChanges

func CheckStringTypeChanges(diffs []TypeDiff, type1, type2 *spec.SchemaProps) []TypeDiff

CheckStringTypeChanges checks for changes to or from a string type

func CheckToFromPrimitiveType

func CheckToFromPrimitiveType(diffs []TypeDiff, type1, type2 interface{}) []TypeDiff

CheckToFromPrimitiveType check for diff to or from a primitive

func CheckToFromRequired

func CheckToFromRequired(required1, required2 bool) (diffs []TypeDiff)

CheckToFromRequired checks for changes to or from a required property

func CompareEnums

func CompareEnums(left, right []interface{}) []TypeDiff

CompareEnums returns added, deleted enum values

func CompareFloatValues

func CompareFloatValues(fieldName string, val1 *float64, val2 *float64, ifGreaterCode SpecChangeCode, ifLessCode SpecChangeCode) []TypeDiff

CompareFloatValues compares a float data item

func CompareIntValues

func CompareIntValues(fieldName string, val1 *int64, val2 *int64, ifGreaterCode SpecChangeCode, ifLessCode SpecChangeCode) []TypeDiff

CompareIntValues compares to int data items

type URLMethod

type URLMethod struct {
	Path   string `json:"path"`
	Method string `json:"method"`
}

URLMethod - combines url and method into a single keyed entity

func (URLMethod) MarshalText

func (p URLMethod) MarshalText() (text []byte, err error)

MarshalText - for serializing as a map key

type URLMethodResponse

type URLMethodResponse struct {
	Path     string `json:"path"`
	Method   string `json:"method"`
	Response string `json:"response"`
}

URLMethodResponse encapsulates these three elements to act as a map key

type URLMethods

type URLMethods map[URLMethod]*PathItemOp

URLMethods allows iteration of endpoints based on url and method