ISSUE #1228: Resolve path where it is an external reference

Author: Elize van der Riet

src/Microsoft.OpenApi.Readers/V3/OpenApiPathItemDeserializer.cs

@@ -56,6 +56,13 @@ public static OpenApiPathItem LoadPathItem(ParseNode node)
         {
             var mapNode = node.CheckMapNode("PathItem");
 
+            var pointer = mapNode.GetReferencePointer();
+            if (pointer != null)
+            {
+                var refObject = mapNode.GetReferencedObject<OpenApiPathItem>(ReferenceType.Path, pointer);
+                return refObject;
+            }
+
             var pathItem = new OpenApiPathItem();
 
             ParseMap(mapNode, pathItem, _pathItemFixedFields, _pathItemPatternFields);

src/Microsoft.OpenApi.Readers/V3/OpenApiV3VersionService.cs

@@ -129,6 +129,20 @@ public OpenApiReference ConvertToOpenApiReference(
                         }
                         id = localSegments[3];
                     }
+                    else if (id.StartsWith("/paths/"))
+                    {
+                        var localSegments = segments[1].Split('/');
+                        if (localSegments.Length == 3)
+                        {
+                            // The reference of a path may contain JSON escape character ~1 for the forward-slash character, replace this otherwise
+                            // the reference cannot be resolved.
+                            id = localSegments[2].Replace("~1", "/");
+                        }
+                        else
+                        {
+                            throw new OpenApiException("Referenced Path mismatch");
+                        }
+                    }
                     else
                     {
                         openApiReference.IsFragrament = true;

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -504,6 +504,9 @@ internal IOpenApiReferenceable ResolveReference(OpenApiReference reference, bool
                     case ReferenceType.Callback:
                         return this.Components.Callbacks[reference.Id];
 
+                    case ReferenceType.Path:
+                        return this.Paths[reference.Id];
+
                     default:
                         throw new OpenApiException(Properties.SRResource.InvalidReferenceType);
                 }

src/Microsoft.OpenApi/Models/ReferenceType.cs

@@ -58,6 +58,11 @@ public enum ReferenceType
         /// <summary>
         /// Tags item.
         /// </summary>
-        [Display("tags")] Tag
+        [Display("tags")] Tag,
+
+        /// <summary>
+        /// Paths item.
+        /// </summary>
+        [Display("paths")] Path
     }
 }

src/Microsoft.OpenApi/Services/OpenApiWalker.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
 using System;
@@ -449,8 +449,12 @@ internal void Walk(OpenApiPathItem pathItem)
 
             if (pathItem != null)
             {
-                Walk(OpenApiConstants.Parameters, () => Walk(pathItem.Parameters));
-                Walk(pathItem.Operations);
+                // The path may be a reference
+                if (!ProcessAsReference(pathItem))
+                {
+                    Walk(OpenApiConstants.Parameters, () => Walk(pathItem.Parameters));
+                    Walk(pathItem.Operations);
+                }
             }
             _visitor.Visit(pathItem as IOpenApiExtensible);