diff

package
v0.25.0 Latest Latest
Warning

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

 Go to latest Published: Mar 17, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ErrDiff diffError = "diff error"
)
View Source 
const StringType = "string"

StringType For identifying string types.

Variables

View Source 
var ArrayType = "array" //nolint:gochecknoglobals // quasi-constant used across package

ArrayType const for array.

View Source 
var ObjectType = "object" //nolint:gochecknoglobals // quasi-constant used across package

ObjectType const for object.

Functions

func JSONMarshal 

func JSONMarshal(t any) ([]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
	// Warning changes are technically non-breaking but can cause behavior changes in client and thus should be reported differently.
	Warning
)

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  any
	Second any
}

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"`
	Extensions     spec.Extensions `json:"extensions"`
}

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
	Info1                 *spec.Info
	Info2                 *spec.Info
	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 definition 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
	// ChangedDescription - Changed a description.
	ChangedDescription
	// AddedDescription - Added a description.
	AddedDescription
	// DeletedDescription - Deleted a description.
	DeletedDescription
	// 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
	// ChangedDefault - Changed default value.
	ChangedDefault
	// AddedDefault - Added a default value.
	AddedDefault
	// DeletedDefault - Deleted a default value.
	DeletedDefault
	// ChangedExample - Changed an example value.
	ChangedExample
	// AddedExample - Added an example value.
	AddedExample
	// DeletedExample - Deleted an example value.
	DeletedExample
	// ChangedCollectionFormat - A collectionFormat has been changed to a collectionFormat whose relative compatibility cannot be determined.
	ChangedCollectionFormat
	// DeletedExtension deleted an extension.
	DeletedExtension
	// AddedExtension added an extension.
	AddedExtension
	// ChangedExtensionValue changed an extension value.
	ChangedExtensionValue
)

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, schema2 *spec.Schema,
	getRefFn1, 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.

func (SpecDifferences) WarningChangeCount 

func (sd SpecDifferences) WarningChangeCount() int

WarningChangeCount Calculates the warning change count.

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 any) (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 any) []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 []any) []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.

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.