Added what-changed docs to readme

and some examples for go-docs

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

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.