Added what-changed docs to readme

and some examples for go-docs

Signed-off-by: Dave Shanley <[email protected]>

README.md

@@ -50,6 +50,13 @@ version of `libopenapi`, which isn't something that can be released as it's cust
 `libopenapi` is the result of years of learning and battle testing OpenAPI in golang. This library represents what would
 have been created, if we knew then - what we know now.
 
+## what-changed: a complete diff engine
+
+Compare Swagger and OpenAPI documents for all changes made across the specification. Every detail is checked across
+all versions of OpenAPI and returns a simple to navigate report of every single change made. 
+
+Everything modified, added or removed is reported, complete with original/new values, line numbers and columns. 
+
 > Need to know which **line**, or **column** number a key or value for something is? **`libopenapi` has you covered**.
 
 ## Comes with an Index and a Resolver
@@ -198,6 +205,61 @@ fmt.Printf("value is %s, the value is on line %d, " +
 ```
 ---
 
+## What changed?
+
+libopenapi comes with a complete **diff engine**
+
+Want to know what changed between two different OpenAPI or Swagger specifications? libopenapi makes this super, super easy.
+
+```go
+// How to compare two different OpenAPI specifications for changes between them.
+
+// load an original OpenAPI 3 specification from bytes
+burgerShopOriginal, _ := ioutil.ReadFile("test_specs/burgershop.openapi.yaml")
+
+// load an **updated** OpenAPI 3 specification from bytes
+burgerShopUpdated, _ := ioutil.ReadFile("test_specs/burgershop.openapi-modified.yaml")
+
+// create a new document from original specification bytes
+originalDoc, err := NewDocument(burgerShopOriginal)
+
+// if anything went wrong, an error is thrown
+if err != nil {
+ panic(fmt.Sprintf("cannot create new document: %e", err))
+}
+
+// create a new document from updated specification bytes
+updatedDoc, err := NewDocument(burgerShopUpdated)
+
+// if anything went wrong, an error is thrown
+if err != nil {
+ panic(fmt.Sprintf("cannot create new document: %e", err))
+}
+
+// Compare documents for all changes made
+documentChanges, errs := CompareDocuments(originalDoc, updatedDoc)
+
+// If anything went wrong when building models for documents.
+if len(errs) > 0 {
+ for i := range errs {
+ fmt.Printf("error: %e\n", errs[i])
+ }
+ panic(fmt.Sprintf("cannot compare documents: %d errors reported", len(errs)))
+}
+
+// Extract SchemaChanges from components changes.
+schemaChanges := documentChanges.ComponentsChanges.SchemaChanges
+
+// Print out some interesting stats about the OpenAPI document changes.
+fmt.Printf("There are %d changes, of which %d are breaking. %v schemas have changes.",
+ documentChanges.TotalChanges(), documentChanges.TotalBreakingChanges(), len(schemaChanges))
+
+```
+
+Every change can be explored and navigated just like you would use the high or low level models.
+
+---
+
 ## But wait, there's more - Mutating the model
 
 Having a read-only model is great, but what about when we want to modify the model and mutate values, or even add new

document.go

@@ -21,6 +21,8 @@ import (
  v2low "github.com/pb33f/libopenapi/datamodel/low/v2"
  v3low "github.com/pb33f/libopenapi/datamodel/low/v3"
  "github.com/pb33f/libopenapi/utils"
+ what_changed "github.com/pb33f/libopenapi/what-changed"
+ "github.com/pb33f/libopenapi/what-changed/model"
  "gopkg.in/yaml.v3"
 )
 
@@ -144,3 +146,42 @@ func (d *document) BuildV3Model() (*DocumentModel[v3high.Document], []error) {
  Model: *highDoc,
  }, nil
 }
+
+// CompareDocuments will accept a left and right Document implementing struct, build a model for the correct
+// version and then compare model documents for changes.
+//
+// If there are any errors when building the models, those errors are returned with a nil pointer for the
+// model.DocumentChanges. If there are any changes found however between either Document, then a pointer to
+// model.DocumentChanges is returned containing every single change, broken down, model by model.
+func CompareDocuments(original, updated Document) (*model.DocumentChanges, []error) {
+ var errors []error
+ if original.GetSpecInfo().SpecType == utils.OpenApi3 && updated.GetSpecInfo().SpecType == utils.OpenApi3 {
+ v3ModelLeft, errs := original.BuildV3Model()
+ if len(errs) > 0 {
+ errors = errs
+ }
+ v3ModelRight, errs := updated.BuildV3Model()
+ if len(errs) > 0 {
+ errors = errs
+ }
+ if len(errors) > 0 {
+ return nil, errors
+ }
+ return what_changed.CompareOpenAPIDocuments(v3ModelLeft.Model.GoLow(), v3ModelRight.Model.GoLow()), nil
+ }
+ if original.GetSpecInfo().SpecType == utils.OpenApi2 && updated.GetSpecInfo().SpecType == utils.OpenApi2 {
+ v2ModelLeft, errs := original.BuildV2Model()
+ if len(errs) > 0 {
+ errors = errs
+ }
+ v2ModelRight, errs := updated.BuildV2Model()
+ if len(errs) > 0 {
+ errors = errs
+ }
+ if len(errors) > 0 {
+ return nil, errors
+ }
+ return what_changed.CompareSwaggerDocuments(v2ModelLeft.Model.GoLow(), v2ModelRight.Model.GoLow()), nil
+ }
+ return nil, nil
+}

document_test.go

@@ -361,6 +361,100 @@ info:
  // url: https://pb33f.io/license
 }
 
+func ExampleCompareDocuments_openAPI() {
+
+ // How to compare two different OpenAPI specifications.
+
+ // load an original OpenAPI 3 specification from bytes
+ burgerShopOriginal, _ := ioutil.ReadFile("test_specs/burgershop.openapi.yaml")
+
+ // load an **updated** OpenAPI 3 specification from bytes
+ burgerShopUpdated, _ := ioutil.ReadFile("test_specs/burgershop.openapi-modified.yaml")
+
+ // create a new document from original specification bytes
+ originalDoc, err := NewDocument(burgerShopOriginal)
+
+ // if anything went wrong, an error is thrown
+ if err != nil {
+ panic(fmt.Sprintf("cannot create new document: %e", err))
+ }
+
+ // create a new document from updated specification bytes
+ updatedDoc, err := NewDocument(burgerShopUpdated)
+
+ // if anything went wrong, an error is thrown
+ if err != nil {
+ panic(fmt.Sprintf("cannot create new document: %e", err))
+ }
+
+ // Compare documents for all changes made
+ documentChanges, errs := CompareDocuments(originalDoc, updatedDoc)
+
+ // If anything went wrong when building models for documents.
+ if len(errs) > 0 {
+ for i := range errs {
+ fmt.Printf("error: %e\n", errs[i])
+ }
+ panic(fmt.Sprintf("cannot compare documents: %d errors reported", len(errs)))
+ }
+
+ // Extract SchemaChanges from components changes.
+ schemaChanges := documentChanges.ComponentsChanges.SchemaChanges
+
+ // Print out some interesting stats about the OpenAPI document changes.
+ fmt.Printf("There are %d changes, of which %d are breaking. %v schemas have changes.",
+ documentChanges.TotalChanges(), documentChanges.TotalBreakingChanges(), len(schemaChanges))
+ //Output: There are 67 changes, of which 17 are breaking. 5 schemas have changes.
+
+}
+
+func ExampleCompareDocuments_swagger() {
+
+ // How to compare two different Swagger specifications.
+
+ // load an original OpenAPI 3 specification from bytes
+ petstoreOriginal, _ := ioutil.ReadFile("test_specs/petstorev2-complete.yaml")
+
+ // load an **updated** OpenAPI 3 specification from bytes
+ petstoreUpdated, _ := ioutil.ReadFile("test_specs/petstorev2-complete-modified.yaml")
+
+ // create a new document from original specification bytes
+ originalDoc, err := NewDocument(petstoreOriginal)
+
+ // if anything went wrong, an error is thrown
+ if err != nil {
+ panic(fmt.Sprintf("cannot create new document: %e", err))
+ }
+
+ // create a new document from updated specification bytes
+ updatedDoc, err := NewDocument(petstoreUpdated)
+
+ // if anything went wrong, an error is thrown
+ if err != nil {
+ panic(fmt.Sprintf("cannot create new document: %e", err))
+ }
+
+ // Compare documents for all changes made
+ documentChanges, errs := CompareDocuments(originalDoc, updatedDoc)
+
+ // If anything went wrong when building models for documents.
+ if len(errs) > 0 {
+ for i := range errs {
+ fmt.Printf("error: %e\n", errs[i])
+ }
+ panic(fmt.Sprintf("cannot compare documents: %d errors reported", len(errs)))
+ }
+
+ // Extract SchemaChanges from components changes.
+ schemaChanges := documentChanges.ComponentsChanges.SchemaChanges
+
+ // Print out some interesting stats about the Swagger document changes.
+ fmt.Printf("There are %d changes, of which %d are breaking. %v schemas have changes.",
+ documentChanges.TotalChanges(), documentChanges.TotalBreakingChanges(), len(schemaChanges))
+ //Output: There are 52 changes, of which 27 are breaking. 5 schemas have changes.
+
+}
+
 func TestDocument_Paths_As_Array(t *testing.T) {
 
  // paths can now be wrapped in an array.

what-changed/what_changed_test.go

@@ -4,6 +4,7 @@
 package what_changed
 
 import (
+ "fmt"
  "github.com/pb33f/libopenapi/datamodel"
  v2 "github.com/pb33f/libopenapi/datamodel/low/v2"
  v3 "github.com/pb33f/libopenapi/datamodel/low/v3"
@@ -124,3 +125,31 @@ func Benchmark_CompareStripe(b *testing.B) {
  CompareOpenAPIDocuments(origDoc, modDoc)
  }
 }
+
+func ExampleCompareOpenAPIDocuments() {
+
+ // Read in a 'left' (original) OpenAPI specification
+ original, _ := ioutil.ReadFile("../test_specs/burgershop.openapi.yaml")
+
+ // Read in a 'right' (modified) OpenAPI specification
+ modified, _ := ioutil.ReadFile("../test_specs/burgershop.openapi-modified.yaml")
+
+ // Extract SpecInfo from bytes
+ infoOriginal, _ := datamodel.ExtractSpecInfo(original)
+ infoModified, _ := datamodel.ExtractSpecInfo(modified)
+
+ // Build OpenAPI Documents from SpecInfo
+ origDocument, _ := v3.CreateDocument(infoOriginal)
+ modDocDocument, _ := v3.CreateDocument(infoModified)
+
+ // Compare OpenAPI Documents and extract to *DocumentChanges
+ changes := CompareOpenAPIDocuments(origDocument, modDocDocument)
+
+ // Extract SchemaChanges from components changes.
+ schemaChanges := changes.ComponentsChanges.SchemaChanges
+
+ // Print out some interesting stats.
+ fmt.Printf("There are %d changes, of which %d are breaking. %v schemas have changes.",
+ changes.TotalChanges(), changes.TotalBreakingChanges(), len(schemaChanges))
+ //Output: There are 67 changes, of which 17 are breaking. 5 schemas have changes.
+}