docs: make the GO.md snippet runnable

reuvenharrison · claude · reuvenharrison · commit 93beb5a27317 · 2026-04-30T17:57:56.000+03:00
The original snippet was diff.Get(&amp;diff.Config{}, spec1, spec2) — but
spec1 and spec2 were undefined and a reader couldn't actually run it.

Adds the imports and the kin-openapi LoadFromFile calls so the example
is a complete, copyable program. Switches to diff.NewConfig() and notes
why (the constructor initializes maps that &amp;diff.Config{} leaves nil).

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/GO.md b/docs/GO.md
@@ -1,16 +1,31 @@
 ## Notes for Go Developers
 
 ### Embedding oasdiff into your program
-The simplest way to get a diff in your go program is:
+Load each spec with the kin-openapi loader, then call `diff.Get`:
+
 ```go
-diff.Get(&diff.Config{}, spec1, spec2)
+import (
+    "github.com/getkin/kin-openapi/openapi3"
+    "github.com/oasdiff/oasdiff/diff"
+)
+
+loader := openapi3.NewLoader()
+
+s1, err := loader.LoadFromFile("base.yaml")
+// handle err
+
+s2, err := loader.LoadFromFile("revision.yaml")
+// handle err
+
+diffReport, err := diff.Get(diff.NewConfig(), s1, s2)
+// handle err
 ```
 
-### Advanced Examples
+Use `diff.NewConfig()` rather than `&diff.Config{}` — the constructor initializes internal maps that the diff engine expects to be non-nil.
+
+### Runnable Examples
 - [diff](https://pkg.go.dev/github.com/oasdiff/oasdiff/diff#example-Get)
 - [breaking changes](https://pkg.go.dev/github.com/oasdiff/oasdiff/diff#example-GetPathsDiff)
 
-
 ### OpenAPI References
-Note that oasdiff expects [OpenAPI References](https://swagger.io/docs/specification/using-ref/) to be resolved.  
-References are normally resolved automatically when you load the spec. In other cases you can resolve refs using [Loader.ResolveRefsIn](https://pkg.go.dev/github.com/getkin/kin-openapi/openapi3#Loader.ResolveRefsIn).
+oasdiff expects [OpenAPI references](https://swagger.io/docs/specification/using-ref/) to be resolved. The kin-openapi loader resolves them automatically when you load the spec; if you build a spec another way, resolve them with [Loader.ResolveRefsIn](https://pkg.go.dev/github.com/getkin/kin-openapi/openapi3#Loader.ResolveRefsIn).
