Added what-changed documentation to methods and structs.

Signed-off-by: Dave Shanley <dave@quobix.com>

what-changed/model/change_types.go

@@ -94,6 +94,8 @@ type Change struct {
 
 // PropertyChanges holds a slice of Change pointers
 type PropertyChanges struct {
+	//Total *int `json:"total,omitempty" yaml:"total,omitempty"`
+	//Breaking *int `json:"breaking,omitempty" yaml:"breaking,omitempty"`
 	Changes []*Change `json:"changes,omitempty" yaml:"changes,omitempty"`
 }
 

what-changed/model/oauth_flows.go

@@ -151,7 +151,8 @@ func (o *OAuthFlowChanges) TotalBreakingChanges() int {
 	return o.PropertyChanges.TotalBreakingChanges()
 }
 
-// CompareOAuthFlow checks a left and a right OAuthFlow object
+// CompareOAuthFlow checks a left and a right OAuthFlow object for changes. If found, returns a pointer to
+// an OAuthFlowChanges instance, or nil if nothing is found.
 func CompareOAuthFlow(l, r *v3.OAuthFlow) *OAuthFlowChanges {
 	if low.AreEqual(l, r) {
 		return nil

what-changed/model/operation.go

@@ -14,6 +14,7 @@ import (
 	"strings"
 )
 
+// OperationChanges represent changes made between two Swagger or OpenAPI Operation objects.
 type OperationChanges struct {
 	PropertyChanges
 	ExternalDocChanges         *ExternalDocChanges           `json:"externalDoc,omitempty" yaml:"externalDoc,omitempty"`
@@ -21,13 +22,14 @@ type OperationChanges struct {
 	ResponsesChanges           *ResponsesChanges             `json:"responses,omitempty" yaml:"responses,omitempty"`
 	SecurityRequirementChanges []*SecurityRequirementChanges `json:"securityRequirements,omitempty" yaml:"securityRequirements,omitempty"`
 
-	// v3
+	// OpenAPI 3+ only changes
 	RequestBodyChanges *RequestBodyChanges         `json:"requestBodies,omitempty" yaml:"requestBodies,omitempty"`
 	ServerChanges      []*ServerChanges            `json:"servers,omitempty" yaml:"servers,omitempty"`
 	ExtensionChanges   *ExtensionChanges           `json:"extensions,omitempty" yaml:"extensions,omitempty"`
 	CallbackChanges    map[string]*CallbackChanges `json:"callbacks,omitempty" yaml:"callbacks,omitempty"`
 }
 
+// TotalChanges returns the total number of changes made between two Swagger or OpenAPI Operation objects.
 func (o *OperationChanges) TotalChanges() int {
 	c := o.PropertyChanges.TotalChanges()
 	if o.ExternalDocChanges != nil {
@@ -57,6 +59,8 @@ func (o *OperationChanges) TotalChanges() int {
 	return c
 }
 
+// TotalBreakingChanges returns the total number of breaking changes made between two Swagger
+// or OpenAPI Operation objects.
 func (o *OperationChanges) TotalBreakingChanges() int {
 	c := o.PropertyChanges.TotalBreakingChanges()
 	if o.ExternalDocChanges != nil {
@@ -84,6 +88,7 @@ func (o *OperationChanges) TotalBreakingChanges() int {
 	return c
 }
 
+// check for properties shared between operations objects.
 func addSharedOperationProperties(left, right low.SharedOperations, changes *[]*Change) []*PropertyCheck {
 	var props []*PropertyCheck
 
@@ -112,6 +117,7 @@ func addSharedOperationProperties(left, right low.SharedOperations, changes *[]*
 	return props
 }
 
+// check shared objects
 func compareSharedOperationObjects(l, r low.SharedOperations, changes *[]*Change, opChanges *OperationChanges) {
 
 	// external docs
@@ -150,6 +156,8 @@ func compareSharedOperationObjects(l, r low.SharedOperations, changes *[]*Change
 
 }
 
+// CompareOperations compares a left and right Swagger or OpenAPI Operation object. If changes are found, returns
+// a pointer to an OperationChanges instance, or nil if nothing is found.
 func CompareOperations(l, r any) *OperationChanges {
 
 	var changes []*Change
@@ -373,6 +381,7 @@ func CompareOperations(l, r any) *OperationChanges {
 	return oc
 }
 
+// check servers property
 func checkServers(lServers, rServers low.NodeReference[[]low.ValueReference[*v3.Server]]) []*ServerChanges {
 
 	var serverChanges []*ServerChanges
@@ -460,6 +469,7 @@ func checkServers(lServers, rServers low.NodeReference[[]low.ValueReference[*v3.
 	return serverChanges
 }
 
+// check security property.
 func checkSecurity(lSecurity, rSecurity low.NodeReference[[]low.ValueReference[*base.SecurityRequirement]],
 	changes *[]*Change, oc any) {
 

what-changed/model/parameter.go

@@ -12,15 +12,16 @@ import (
 	"reflect"
 )
 
+// ParameterChanges represents changes found between Swagger or OpenAPI Parameter objects.
 type ParameterChanges struct {
 	PropertyChanges
 	SchemaChanges    *SchemaChanges    `json:"schemas,omitempty" yaml:"schemas,omitempty"`
 	ExtensionChanges *ExtensionChanges `json:"extensions,omitempty" yaml:"extensions,omitempty"`
 
-	// v2 change types
+	// Swagger supports Items.
 	ItemsChanges *ItemsChanges `json:"items,omitempty" yaml:"items,omitempty"`
 
-	// v3 change types
+	// OpenAPI supports examples and content types.
 	ExamplesChanges map[string]*ExampleChanges   `json:"examples,omitempty" yaml:"examples,omitempty"`
 	ContentChanges  map[string]*MediaTypeChanges `json:"content,omitempty" yaml:"content,omitempty"`
 }
@@ -191,14 +192,13 @@ func addCommonParameterProperties(left, right low.SharedParameters, changes *[]*
 	return props
 }
 
+// CompareParametersV3 is amn OpenAPI type safe proxy for CompareParameters
 func CompareParametersV3(l, r *v3.Parameter) *ParameterChanges {
 	return CompareParameters(l, r)
 }
 
-func CompareParametersV2(l, r *v2.Parameter) *ParameterChanges {
+// CompareParameters compares a left and right Swagger or OpenAPI Parameter object for any changes. If found returns
-	return CompareParameters(l, r)
+// a pointer to ParameterChanges. If nothing is found, returns nil.
-}
-
 func CompareParameters(l, r any) *ParameterChanges {
 
 	var changes []*Change

what-changed/model/path_item.go

@@ -10,6 +10,7 @@ import (
 	"reflect"
 )
 
+// PathItemChanges represents changes found between to Swagger or OpenAPI PathItem object.
 type PathItemChanges struct {
 	PropertyChanges
 	GetChanges       *OperationChanges   `json:"get,omitempty" yaml:"get,omitempty"`
@@ -25,6 +26,7 @@ type PathItemChanges struct {
 	ExtensionChanges *ExtensionChanges   `json:"extensions,omitempty" yaml:"extensions,omitempty"`
 }
 
+// TotalChanges returns the total number of changes found between two Swagger or OpenAPI PathItems
 func (p *PathItemChanges) TotalChanges() int {
 	c := p.PropertyChanges.TotalChanges()
 	if p.GetChanges != nil {
@@ -63,6 +65,7 @@ func (p *PathItemChanges) TotalChanges() int {
 	return c
 }
 
+// TotalBreakingChanges returns the total number of breaking changes found between two Swagger or OpenAPI PathItems
 func (p *PathItemChanges) TotalBreakingChanges() int {
 	c := p.PropertyChanges.TotalBreakingChanges()
 	if p.GetChanges != nil {
@@ -103,10 +106,13 @@ type opCheck struct {
 	changes *OperationChanges
 }
 
+// ComparePathItemsV3 is an OpenAPI typesafe proxy method for ComparePathItems
 func ComparePathItemsV3(l, r *v3.PathItem) *PathItemChanges {
 	return ComparePathItems(l, r)
 }
 
+// ComparePathItems compare a left and right Swagger or OpenAPI PathItem object for changes. If found, returns
+// a pointer to PathItemChanges, or returns nil if nothing is found.
 func ComparePathItems(l, r any) *PathItemChanges {
 
 	var changes []*Change

what-changed/model/paths.go

@@ -11,12 +11,14 @@ import (
 	"sync"
 )
 
+// PathsChanges represents changes found between two Swagger or OpenAPI Paths Objects.
 type PathsChanges struct {
 	PropertyChanges
 	PathItemsChanges map[string]*PathItemChanges `json:"pathItems,omitempty" yaml:"pathItems,omitempty"`
 	ExtensionChanges *ExtensionChanges           `json:"extensions,omitempty" yaml:"extensions,omitempty"`
 }
 
+// TotalChanges returns the total number of changes between two Swagger or OpenAPI Paths Objects
 func (p *PathsChanges) TotalChanges() int {
 	c := p.PropertyChanges.TotalChanges()
 	for k := range p.PathItemsChanges {
@@ -28,6 +30,7 @@ func (p *PathsChanges) TotalChanges() int {
 	return c
 }
 
+// TotalBreakingChanges returns tht total number of changes found between two Swagger or OpenAPI Path Objects
 func (p *PathsChanges) TotalBreakingChanges() int {
 	c := p.PropertyChanges.TotalBreakingChanges()
 	for k := range p.PathItemsChanges {
@@ -36,6 +39,8 @@ func (p *PathsChanges) TotalBreakingChanges() int {
 	return c
 }
 
+// ComparePaths compares a left and right Swagger or OpenAPI Paths Object for changes. If found, returns a pointer
+// to a PathsChanges instance. Returns nil if nothing is found.
 func ComparePaths(l, r any) *PathsChanges {
 
 	var changes []*Change

what-changed/model/request_body.go

@@ -8,12 +8,14 @@ import (
 	"github.com/pb33f/libopenapi/datamodel/low/v3"
 )
 
+// RequestBodyChanges represents changes made between two OpenAPI RequestBody Objects
 type RequestBodyChanges struct {
 	PropertyChanges
 	ContentChanges   map[string]*MediaTypeChanges `json:"content,omitempty" yaml:"content,omitempty"`
 	ExtensionChanges *ExtensionChanges            `json:"extensions,omitempty" yaml:"extensions,omitempty"`
 }
 
+// TotalChanges returns the total number of changes found between two OpenAPI RequestBody objects
 func (rb *RequestBodyChanges) TotalChanges() int {
 	c := rb.PropertyChanges.TotalChanges()
 	for k := range rb.ContentChanges {
@@ -25,6 +27,7 @@ func (rb *RequestBodyChanges) TotalChanges() int {
 	return c
 }
 
+// TotalBreakingChanges returns the total number of breaking changes found between OpenAPI RequestBody objects
 func (rb *RequestBodyChanges) TotalBreakingChanges() int {
 	c := rb.PropertyChanges.TotalBreakingChanges()
 	for k := range rb.ContentChanges {
@@ -33,6 +36,8 @@ func (rb *RequestBodyChanges) TotalBreakingChanges() int {
 	return c
 }
 
+// CompareRequestBodies compares a left and right OpenAPI RequestBody object for changes. If found returns a pointer
+// to a RequestBodyChanges instance. Returns nil if nothing was found.
 func CompareRequestBodies(l, r *v3.RequestBody) *RequestBodyChanges {
 	if low.AreEqual(l, r) {
 		return nil

what-changed/model/response.go

@@ -10,21 +10,23 @@ import (
 	"reflect"
 )
 
+// ResponseChanges represents changes found between two Swagger or OpenAPI Response objects.
 type ResponseChanges struct {
 	PropertyChanges
 	ExtensionChanges *ExtensionChanges         `json:"extensions,omitempty" yaml:"extensions,omitempty"`
 	HeadersChanges   map[string]*HeaderChanges `json:"headers,omitempty" yaml:"headers,omitempty"`
 
-	// v2
+	// Swagger Response Properties.
 	SchemaChanges   *SchemaChanges   `json:"schemas,omitempty" yaml:"schemas,omitempty"`
 	ExamplesChanges *ExamplesChanges `json:"examples,omitempty" yaml:"examples,omitempty"`
 
-	// v3
+	// OpenAPI Response Properties.
 	ContentChanges map[string]*MediaTypeChanges `json:"content,omitempty" yaml:"content,omitempty"`
 	LinkChanges    map[string]*LinkChanges      `json:"links,omitempty" yaml:"links,omitempty"`
 	ServerChanges  *ServerChanges               `json:"server,omitempty" yaml:"server,omitempty"`
 }
 
+// TotalChanges returns the total number of changes found between two Swagger or OpenAPI Response Objects
 func (r *ResponseChanges) TotalChanges() int {
 	c := r.PropertyChanges.TotalChanges()
 	if r.ExtensionChanges != nil {
@@ -48,6 +50,8 @@ func (r *ResponseChanges) TotalChanges() int {
 	return c
 }
 
+// TotalBreakingChanges returns the total number of breaking changes found between two swagger or OpenAPI
+// Response Objects
 func (r *ResponseChanges) TotalBreakingChanges() int {
 	c := r.PropertyChanges.TotalBreakingChanges()
 	if r.SchemaChanges != nil {
@@ -65,14 +69,18 @@ func (r *ResponseChanges) TotalBreakingChanges() int {
 	return c
 }
 
+// CompareResponseV2 is a Swagger type safe proxy for CompareResponse
 func CompareResponseV2(l, r *v2.Response) *ResponseChanges {
 	return CompareResponse(l, r)
 }
 
+// CompareResponseV3 is an OpenAPI type safe proxy for CompareResponse
 func CompareResponseV3(l, r *v3.Response) *ResponseChanges {
 	return CompareResponse(l, r)
 }
 
+// CompareResponse compares a left and right Swagger or OpenAPI Response object. If anything is found
+// a pointer to a ResponseChanges is returned, otherwise it returns nil.
 func CompareResponse(l, r any) *ResponseChanges {
 
 	var changes []*Change

what-changed/model/responses.go

@@ -10,6 +10,7 @@ import (
 	"reflect"
 )
 
+// ResponsesChanges represents changes made between two Swagger or OpenAPI Responses objects.
 type ResponsesChanges struct {
 	PropertyChanges
 	ResponseChanges  map[string]*ResponseChanges `json:"response,omitempty" yaml:"response,omitempty"`
@@ -17,6 +18,7 @@ type ResponsesChanges struct {
 	ExtensionChanges *ExtensionChanges           `json:"extensions,omitempty" yaml:"extensions,omitempty"`
 }
 
+// TotalChanges returns the total number of changes found between two Swagger or OpenAPI Responses objects
 func (r *ResponsesChanges) TotalChanges() int {
 	c := r.PropertyChanges.TotalChanges()
 	for k := range r.ResponseChanges {
@@ -31,6 +33,8 @@ func (r *ResponsesChanges) TotalChanges() int {
 	return c
 }
 
+// TotalBreakingChanges returns the total number of changes found between two Swagger or OpenAPI
+// Responses Objects
 func (r *ResponsesChanges) TotalBreakingChanges() int {
 	c := r.PropertyChanges.TotalBreakingChanges()
 	for k := range r.ResponseChanges {
@@ -42,6 +46,8 @@ func (r *ResponsesChanges) TotalBreakingChanges() int {
 	return c
 }
 
+// CompareResponses compares a left and right Swagger or OpenAPI Responses object for any changes. If found
+// returns a pointer to ResponsesChanges, or returns nil.
 func CompareResponses(l, r any) *ResponsesChanges {
 
 	var changes []*Change

what-changed/model/schema.go

@@ -129,6 +129,8 @@ func (s *SchemaChanges) TotalBreakingChanges() int {
 	return t
 }
 
+// CompareSchemas accepts a left and right SchemaProxy and checks for changes. If anything is found, returns
+// a pointer to SchemaChanges, otherwise returns nil
 func CompareSchemas(l, r *base.SchemaProxy) *SchemaChanges {
 	sc := new(SchemaChanges)
 	var changes []*Change

what-changed/model/scopes.go

@@ -9,11 +9,13 @@ import (
 	v3 "github.com/pb33f/libopenapi/datamodel/low/v3"
 )
 
+// ScopesChanges represents changes between two Swagger Scopes Objects
 type ScopesChanges struct {
 	PropertyChanges
 	ExtensionChanges *ExtensionChanges `json:"extensions,omitempty" yaml:"extensions,omitempty"`
 }
 
+// TotalChanges returns the total changes found between two Swagger Scopes objects.
 func (s *ScopesChanges) TotalChanges() int {
 	c := s.PropertyChanges.TotalChanges()
 	if s.ExtensionChanges != nil {
@@ -22,10 +24,13 @@ func (s *ScopesChanges) TotalChanges() int {
 	return c
 }
 
+// TotalBreakingChanges returns the total number of breaking changes between two Swagger Scopes objects.
 func (s *ScopesChanges) TotalBreakingChanges() int {
 	return s.PropertyChanges.TotalBreakingChanges()
 }
 
+// CompareScopes compares a left and right Swagger Scopes objects for changes. If anything is found, returns
+// a pointer to ScopesChanges, or returns nil if nothing is found.
 func CompareScopes(l, r *v2.Scopes) *ScopesChanges {
 	if low.AreEqual(l, r) {
 		return nil

what-changed/model/security_requirement.go

@@ -10,28 +10,23 @@ import (
 	"gopkg.in/yaml.v3"
 )
 
+// SecurityRequirementChanges represents changes found between two SecurityRequirement Objects.
 type SecurityRequirementChanges struct {
 	PropertyChanges
 }
 
+// TotalChanges returns the total number of changes between two SecurityRequirement Objects.
 func (s *SecurityRequirementChanges) TotalChanges() int {
 	return s.PropertyChanges.TotalChanges()
 }
 
+// TotalBreakingChanges returns the total number of breaking changes between two SecurityRequirement Objects.
 func (s *SecurityRequirementChanges) TotalBreakingChanges() int {
 	return s.PropertyChanges.TotalBreakingChanges()
 }
 
-func removedSecurityRequirement(vn *yaml.Node, name string, changes *[]*Change) {
+// CompareSecurityRequirement compares left and right SecurityRequirement objects for changes. If anything
-	CreateChange(changes, ObjectRemoved, v3.SecurityLabel,
+// is found, then a pointer to SecurityRequirementChanges is returned, otherwise nil.
-		vn, nil, true, name, nil)
-}
-
-func addedSecurityRequirement(vn *yaml.Node, name string, changes *[]*Change) {
-	CreateChange(changes, ObjectAdded, v3.SecurityLabel,
-		nil, vn, false, nil, name)
-}
-
 func CompareSecurityRequirement(l, r *base.SecurityRequirement) *SecurityRequirementChanges {
 
 	var changes []*Change
@@ -45,6 +40,17 @@ func CompareSecurityRequirement(l, r *base.SecurityRequirement) *SecurityRequire
 	return sc
 }
 
+func removedSecurityRequirement(vn *yaml.Node, name string, changes *[]*Change) {
+	CreateChange(changes, ObjectRemoved, v3.SecurityLabel,
+		vn, nil, true, name, nil)
+}
+
+func addedSecurityRequirement(vn *yaml.Node, name string, changes *[]*Change) {
+	CreateChange(changes, ObjectAdded, v3.SecurityLabel,
+		nil, vn, false, nil, name)
+}
+
+// tricky to do this correctly, this is my solution.
 func checkSecurityRequirement(lSec, rSec map[low.KeyReference[string]]low.ValueReference[[]low.ValueReference[string]],
 	changes *[]*Change) {
 

what-changed/model/security_scheme.go

@@ -10,15 +10,19 @@ import (
 	"reflect"
 )
 
+// SecuritySchemeChanges represents changes made between Swagger or OpenAPI SecurityScheme Objects.
 type SecuritySchemeChanges struct {
 	PropertyChanges
 	ExtensionChanges *ExtensionChanges `json:"extensions,omitempty" yaml:"extensions,omitempty"`
-	// v3
+
+	// OpenAPI Version
 	OAuthFlowChanges *OAuthFlowsChanges `json:"oAuthFlow,omitempty" yaml:"oAuthFlow,omitempty"`
-	// v2
+
+	// Swagger Version
 	ScopesChanges *ScopesChanges `json:"scopes,omitempty" yaml:"scopes,omitempty"`
 }
 
+// TotalChanges represents total changes found between two Swagger or OpenAPI SecurityScheme instances.
 func (ss *SecuritySchemeChanges) TotalChanges() int {
 	c := ss.PropertyChanges.TotalChanges()
 	if ss.OAuthFlowChanges != nil {
@@ -33,6 +37,7 @@ func (ss *SecuritySchemeChanges) TotalChanges() int {
 	return c
 }
 
+// TotalBreakingChanges returns total number of breaking changes between two SecurityScheme Objects.
 func (ss *SecuritySchemeChanges) TotalBreakingChanges() int {
 	c := ss.PropertyChanges.TotalBreakingChanges()
 	if ss.OAuthFlowChanges != nil {
@@ -44,14 +49,18 @@ func (ss *SecuritySchemeChanges) TotalBreakingChanges() int {
 	return c
 }
 
+// CompareSecuritySchemesV2 is a Swagger type safe proxy for CompareSecuritySchemes
 func CompareSecuritySchemesV2(l, r *v2.SecurityScheme) *SecuritySchemeChanges {
 	return CompareSecuritySchemes(l, r)
 }
 
+// CompareSecuritySchemesV3 is an OpenAPI type safe proxt for CompareSecuritySchemes
 func CompareSecuritySchemesV3(l, r *v3.SecurityScheme) *SecuritySchemeChanges {
 	return CompareSecuritySchemes(l, r)
 }
 
+// CompareSecuritySchemes compares left and right Swagger or OpenAPI Security Scheme objects for changes.
+// If anything is found, returns a pointer to *SecuritySchemeChanges or nil if nothing is found.
 func CompareSecuritySchemes(l, r any) *SecuritySchemeChanges {
 
 	var props []*PropertyCheck

what-changed/model/server.go

@@ -8,11 +8,13 @@ import (
 	"github.com/pb33f/libopenapi/datamodel/low/v3"
 )
 
+// ServerChanges represents changes found between two OpenAPI Server Objects
 type ServerChanges struct {
 	PropertyChanges
 	ServerVariableChanges map[string]*ServerVariableChanges `json:"serverVariables,omitempty" yaml:"serverVariables,omitempty"`
 }
 
+// TotalChanges returns total changes found between two OpenAPI Server Objects
 func (s *ServerChanges) TotalChanges() int {
 	c := s.PropertyChanges.TotalChanges()
 	for k := range s.ServerVariableChanges {
@@ -21,6 +23,7 @@ func (s *ServerChanges) TotalChanges() int {
 	return c
 }
 
+// TotalBreakingChanges returns the total number of breaking changes found between two OpenAPI Server objects.
 func (s *ServerChanges) TotalBreakingChanges() int {
 	c := s.PropertyChanges.TotalBreakingChanges()
 	for k := range s.ServerVariableChanges {
@@ -29,6 +32,8 @@ func (s *ServerChanges) TotalBreakingChanges() int {
 	return c
 }
 
+// CompareServers compares two OpenAPI Server objects for any changes. If anything is found, returns a pointer
+// to a ServerChanges instance, or returns nil if nothing is found.
 func CompareServers(l, r *v3.Server) *ServerChanges {
 	if low.AreEqual(l, r) {
 		return nil

what-changed/model/server_variable.go

@@ -8,10 +8,13 @@ import (
 	"github.com/pb33f/libopenapi/datamodel/low/v3"
 )
 
+// ServerVariableChanges represents changes found between two OpenAPI ServerVariable Objects
 type ServerVariableChanges struct {
 	PropertyChanges
 }
 
+// CompareServerVariables compares a left and right OpenAPI ServerVariable object for changes.
+// If anything is found, returns a pointer to a ServerVariableChanges instance, otherwise returns nil.
 func CompareServerVariables(l, r *v3.ServerVariable) *ServerVariableChanges {
 	if low.AreEqual(l, r) {
 		return nil