fixing example filtering logic

this one is persistent!

Author: daveshanley

index/extract_refs.go

@@ -58,17 +58,20 @@ func isOpenAPIExampleKeywordSegment(seenPath []string, idx int) bool {
 	}
 }
 
-// underOpenAPIExamplePayloadPath reports whether seenPath points to raw example payload content,
-// not the Example Object itself. This lets the walker keep traversing legitimate Example Objects
-// for $ref values while still skipping sample data under example/value/dataValue.
+// underOpenAPIExamplePayloadPath reports whether seenPath points to raw example payload content.
+// A bare `example` path is not payload by itself because libopenapi still supports a direct
+// `$ref` wrapper there for bundling. Once traversal moves below `example`, or into an Example
+// Object's `value`/`dataValue`, the path is payload and nested `$ref` keys should be ignored.
 func underOpenAPIExamplePayloadPath(seenPath []string) bool {
 	for i := range seenPath {
 		if !isOpenAPIExampleKeywordSegment(seenPath, i) {
 			continue
 		}
 		switch seenPath[i] {
 		case "example":
-			return true
+			if len(seenPath) > i+1 {
+				return true
+			}
 		case "examples":
 			if len(seenPath) > i+2 {
 				switch seenPath[i+2] {
@@ -81,6 +84,18 @@ func underOpenAPIExamplePayloadPath(seenPath []string) bool {
 	return false
 }
 
+// isDirectOpenAPIExampleValuePath reports whether seenPath points at the value of an OpenAPI
+// `example` field itself. This is used to allow a top-level `$ref` wrapper while still skipping
+// traversal into arbitrary example payload objects.
+func isDirectOpenAPIExampleValuePath(seenPath []string) bool {
+	for i := range seenPath {
+		if seenPath[i] == "example" && isOpenAPIExampleKeywordSegment(seenPath, i) && len(seenPath) == i+1 {
+			return true
+		}
+	}
+	return false
+}
+
 // ExtractRefs will return a deduplicated slice of references for every unique ref found in the document.
 // The total number of refs, will generally be much higher, you can extract those from GetRawReferenceCount()
 func (index *SpecIndex) ExtractRefs(ctx context.Context, node, parent *yaml.Node, seenPath []string, level int, poly bool, pName string) []*Reference {

index/extract_refs_test.go

@@ -744,7 +744,7 @@ func TestUnderOpenAPIExamplePayloadPath(t *testing.T) {
 		want bool
 	}{
 		{"empty", nil, false},
-		{"example_payload", []string{"paths", "get", "responses", "200", "content", "application/json", "schema", "example"}, true},
+		{"example_root", []string{"paths", "get", "responses", "200", "content", "application/json", "schema", "example"}, false},
 		{"nested_under_example_payload", []string{"components", "schemas", "Foo", "example", "nested"}, true},
 		{"examples_collection", []string{"components", "examples"}, false},
 		{"example_object_entry", []string{"components", "examples", "ReusableExample"}, false},
@@ -753,7 +753,7 @@ func TestUnderOpenAPIExamplePayloadPath(t *testing.T) {
 		{"examples_data_value_payload", []string{"components", "examples", "sample", "dataValue"}, true},
 		{"property_named_example", []string{"components", "schemas", "Foo", "properties", "example"}, false},
 		{"property_named_examples_value", []string{"components", "schemas", "Foo", "properties", "examples", "value"}, false},
-		{"real_example_after_property_example", []string{"components", "schemas", "Foo", "properties", "example", "example"}, true},
+		{"real_example_after_property_example", []string{"components", "schemas", "Foo", "properties", "example", "example"}, false},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -1070,3 +1070,41 @@ components:
 	assert.False(t, rawRefs["#/components/schemas/ShouldNotIndex"])
 	assert.False(t, rawRefs["#/components/schemas/ShouldNotIndexData"])
 }
+
+func TestSpecIndex_ExtractRefs_SchemaExampleRefIndexedButNestedPayloadRefsIgnored(t *testing.T) {
+	spec := `openapi: 3.2.0
+info:
+  title: Schema example refs
+  version: 1.0.0
+components:
+  schemas:
+    UsesExampleRef:
+      type: object
+      example:
+        $ref: '#/components/examples/ReusableExample'
+    InlineExamplePayload:
+      type: object
+      example:
+        nested:
+          $ref: '#/components/schemas/ShouldNotIndex'
+    ShouldNotIndex:
+      type: object
+  examples:
+    ReusableExample:
+      value:
+        ok: true
+`
+
+	var rootNode yaml.Node
+	_ = yaml.Unmarshal([]byte(spec), &rootNode)
+
+	idx := NewSpecIndexWithConfig(&rootNode, CreateOpenAPIIndexConfig())
+
+	rawRefs := make(map[string]bool)
+	for _, ref := range idx.GetAllReferences() {
+		rawRefs[ref.RawRef] = true
+	}
+
+	assert.True(t, rawRefs["#/components/examples/ReusableExample"])
+	assert.False(t, rawRefs["#/components/schemas/ShouldNotIndex"])
+}

index/extract_refs_walk.go

@@ -90,6 +90,9 @@ func (index *SpecIndex) walkChildExtractRefs(node, parent *yaml.Node, state *ext
 	if underOpenAPIExamplePayloadPath(state.seenPath) {
 		return nil
 	}
+	if isDirectOpenAPIExampleValuePath(state.seenPath) && !isDirectOpenAPIExampleRefNode(node) {
+		return nil
+	}
 	state.level++
 	if isPoly, _ := index.checkPolymorphicNode(state.prev); isPoly {
 		state.poly = true
@@ -100,6 +103,10 @@ func (index *SpecIndex) walkChildExtractRefs(node, parent *yaml.Node, state *ext
 	return index.ExtractRefs(state.ctx, node, parent, state.seenPath, state.level, state.poly, state.polyName)
 }
 
+func isDirectOpenAPIExampleRefNode(node *yaml.Node) bool {
+	return utils.IsNodeMap(node) && utils.GetRefValueNode(node) != nil && len(node.Content) == 2
+}
+
 func (index *SpecIndex) handleExtractRefsKey(
 	node, parent *yaml.Node,
 	state *extractRefsState,