openapi3: implement circular reference backtracking (getkin#970)

* feat(loader): implement reference back-tracking * update docs * address review comments * update docs and readme * fix inconsistency * adjust readme
AnatolyRugalev · Jun 27, 2024 · 3820951 · 3820951
1 parent 57624b3
commit 3820951
Show file tree

Hide file tree

Showing 12 changed files with 169 additions and 175 deletions.
diff --git a/.github/docs/openapi3.txt b/.github/docs/openapi3.txt
@@ -55,8 +55,6 @@ var (
 	// ErrSchemaInputInf may be returned when validating a number
 	ErrSchemaInputInf = errors.New("floating point Inf is not allowed")
 )
-var CircularReferenceCounter = 3
-var CircularReferenceError = "kin-openapi bug found: circular schema reference not handled"
 var DefaultReadFromURI = URIMapCache(ReadFromURIs(ReadFromHTTP(http.DefaultClient), ReadFromFile))
     DefaultReadFromURI returns a caching ReadFromURIFunc which can read remote
     HTTP URIs and local file URIs.

diff --git a/README.md b/README.md
@@ -303,6 +303,9 @@ for _, path := range doc.Paths.InMatchingOrder() {
 
 ## CHANGELOG: Sub-v1 breaking API changes
 
+### v0.126.0
+* `openapi3.CircularReferenceError` and `openapi3.CircularReferenceCounter` are removed. `openapi3.Loader` now implements reference backtracking, so any kind of circular references should be properly resolved.
+
 ### v0.125.0
 * The `openapi3filter.ErrFunc` and `openapi3filter.LogFunc` func types now take the validated request's context as first argument.
 

diff --git a/cmd/validate/main.go b/cmd/validate/main.go
@@ -12,11 +12,6 @@ import (
 	"github.com/getkin/kin-openapi/openapi3"
 )
 
-var (
-	defaultCircular = openapi3.CircularReferenceCounter
-	circular        = flag.Int("circular", defaultCircular, "bump this (upper) limit when there's trouble with cyclic schema references")
-)
-
 var (
 	defaultDefaults = true
 	defaults        = flag.Bool("defaults", defaultDefaults, "when false, disables schemas' default field validation")
@@ -59,7 +54,6 @@ func main() {
 
 	switch {
 	case vd.OpenAPI == "3" || strings.HasPrefix(vd.OpenAPI, "3."):
-		openapi3.CircularReferenceCounter = *circular
 		loader := openapi3.NewLoader()
 		loader.IsExternalRefsAllowed = *ext
 
@@ -90,9 +84,6 @@ func main() {
 
 	case vd.OpenAPI == "2" || strings.HasPrefix(vd.OpenAPI, "2."),
 		vd.Swagger == "2" || strings.HasPrefix(vd.Swagger, "2."):
-		if *circular != defaultCircular {
-			log.Fatal("Flag --circular is only for OpenAPIv3")
-		}
 		if *defaults != defaultDefaults {
 			log.Fatal("Flag --defaults is only for OpenAPIv3")
 		}

diff --git a/openapi3/issue570_test.go b/openapi3/issue570_test.go
@@ -9,5 +9,5 @@ import (
 func TestIssue570(t *testing.T) {
 	loader := NewLoader()
 	_, err := loader.LoadFromFile("testdata/issue570.json")
-	require.ErrorContains(t, err, CircularReferenceError)
+	require.NoError(t, err)
 }
diff --git a/openapi3/issue615_test.go b/openapi3/issue615_test.go
@@ -9,21 +9,6 @@ import (
 )
 
 func TestIssue615(t *testing.T) {
-	{
-		var old int
-		old, openapi3.CircularReferenceCounter = openapi3.CircularReferenceCounter, 1
-		defer func() { openapi3.CircularReferenceCounter = old }()
-
-		loader := openapi3.NewLoader()
-		loader.IsExternalRefsAllowed = true
-		_, err := loader.LoadFromFile("testdata/recursiveRef/issue615.yml")
-		require.ErrorContains(t, err, openapi3.CircularReferenceError)
-	}
-
-	var old int
-	old, openapi3.CircularReferenceCounter = openapi3.CircularReferenceCounter, 4
-	defer func() { openapi3.CircularReferenceCounter = old }()
-
 	loader := openapi3.NewLoader()
 	loader.IsExternalRefsAllowed = true
 	doc, err := loader.LoadFromFile("testdata/recursiveRef/issue615.yml")

diff --git a/openapi3/issue796_test.go b/openapi3/issue796_test.go
@@ -7,11 +7,6 @@ import (
 )
 
 func TestIssue796(t *testing.T) {
-	var old int
-	// Need to set CircularReferenceCounter to > 10
-	old, CircularReferenceCounter = CircularReferenceCounter, 20
-	defer func() { CircularReferenceCounter = old }()
-
 	loader := NewLoader()
 	doc, err := loader.LoadFromFile("testdata/issue796.yml")
 	require.NoError(t, err)

diff --git a/openapi3/load_cicular_ref_with_external_file_test.go b/openapi3/load_cicular_ref_with_external_file_test.go
@@ -47,6 +47,19 @@ func TestLoadCircularRefFromFile(t *testing.T) {
 	bar.Value.Properties["foo"] = &openapi3.SchemaRef{Ref: "#/components/schemas/Foo", Value: foo.Value}
 	foo.Value.Properties["bar"] = &openapi3.SchemaRef{Ref: "#/components/schemas/Bar", Value: bar.Value}
 
+	bazNestedRef := &openapi3.SchemaRef{Ref: "./baz.yml#/BazNested"}
+	array := openapi3.NewArraySchema()
+	array.Items = bazNestedRef
+	bazNested := &openapi3.Schema{Properties: map[string]*openapi3.SchemaRef{
+		"bazArray": {
+			Value: &openapi3.Schema{
+				Items: bazNestedRef,
+			},
+		},
+		"baz": bazNestedRef,
+	}}
+	bazNestedRef.Value = bazNested
+
 	want := &openapi3.T{
 		OpenAPI: "3.0.3",
 		Info: &openapi3.Info{
@@ -57,6 +70,7 @@ func TestLoadCircularRefFromFile(t *testing.T) {
 			Schemas: openapi3.Schemas{
 				"Foo": foo,
 				"Bar": bar,
+				"Baz": bazNestedRef,
 			},
 		},
 	}