Improve reference validator

- Improve handling of circular references.
- Improve the path.

Author: martincostello

src/Microsoft.OpenApi/Validations/Rules/OpenApiDocumentRules.cs

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
+using System;
 using System.Text.Json.Nodes;
 using Microsoft.OpenApi.Reader;
 
@@ -80,9 +81,28 @@ public override void Visit(IOpenApiSchema schema)
 
             private void ValidateSchemaReference(OpenApiSchemaReference reference)
             {
-                if (reference.RecursiveTarget is not null)
+                // Trim off the leading "#/" as the context is already at the root of the document
+                var segment =
+#if NET8_0_OR_GREATER
+                    $"{PathString[2..]}/$ref";
+#else
+                    PathString.Substring(2) + "/$ref";
+#endif
+
+                try
+                {
+                    if (reference.RecursiveTarget is not null)
+                    {
+                        return;
+                    }
+                }
+                catch (InvalidOperationException ex)
                 {
                     // The reference was followed to a valid schema somewhere in the document
+                    context.Enter(segment);
+                    context.CreateWarning(ruleName, ex.Message);
+                    context.Exit();
+
                     return;
                 }
 
@@ -109,14 +129,6 @@ private void ValidateSchemaReference(OpenApiSchemaReference reference)
 
                     if (!isValid)
                     {
-                        // Trim off the leading "#/" as the context is already at the root of the document
-                        var segment =
-#if NET8_0_OR_GREATER
-                            PathString[2..];
-#else
-                            PathString.Substring(2);
-#endif
-
                         context.Enter(segment);
                         context.CreateWarning(ruleName, string.Format(SRResource.Validation_SchemaReferenceDoesNotExist, id));
                         context.Exit();

test/Microsoft.OpenApi.Tests/Validations/OpenApiDocumentValidationTests.cs

@@ -129,6 +129,6 @@ public static void ValidateSchemaReferencesAreInvalid()
         Assert.NotNull(errors);
         var error = Assert.Single(errors);
         Assert.Equal("The schema reference '#/components/schemas/Pet' does not point to an existing schema.", error.Message);
-        Assert.Equal("#/paths/~1pets/get/responses/200/content/application~1json/schema", error.Pointer);
+        Assert.Equal("#/paths/~1pets/get/responses/200/content/application~1json/schema/$ref", error.Pointer);
     }
 }