Update Reference implementation to handle all tag, security scheme, and $ref-style pointers correctly. (#90)

* Update name from IExtension and IReference to IExtensible and IReferenceable

* Update Reference implementation to correctly handle tag, security scheme, and other ref-style referenceable objects.

* Add GetReferencedObject to all applicable deserializers

* Move files for ReferenceService and remove duplicate implementation of LoadTag

* Add OperationTests. This writes both Tag and SecurityScheme as references.

* Always write tag as strings regardless of whether Pointer exists in the Operation.

* Remove ReferenceService Base

* Add Unit Test for full document reading including schema/tag/securityScheme. One test is not working properly since we can't do dictionary comparison with securityScheme being the key right now, so I'm using JsonConvert as workaround for the equality issue.

* Minor cleanup for RootNode and ParsingContext

Author: PerthCharern

src/Microsoft.OpenApi.Readers/Interface/IOpenApiReferenceService.cs

@@ -17,6 +17,10 @@
     <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\Microsoft.OpenApi.xml</DocumentationFile>
   </PropertyGroup>
 
+  <ItemGroup>
+    <Compile Remove="ReferenceServices\OpenApiReferenceServiceBase.cs" />
+  </ItemGroup>
+
   <ItemGroup>
     <PackageReference Include="SharpYaml" Version="1.6.1" />
   </ItemGroup>

src/Microsoft.OpenApi.Readers/Interface/OpenApiReferenceServiceBase.cs

@@ -5,13 +5,14 @@
 
 using System.IO;
 using System.Linq;
+using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.Interface;
 using Microsoft.OpenApi.Readers.ParseNodes;
-using SharpYaml;
-using SharpYaml.Serialization;
-using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Readers.ReferenceServices;
 using Microsoft.OpenApi.Readers.V2;
 using Microsoft.OpenApi.Readers.V3;
+using SharpYaml;
+using SharpYaml.Serialization;
 
 namespace Microsoft.OpenApi.Readers
 {
@@ -69,13 +70,13 @@ public OpenApiDocument Read(Stream input, out OpenApiDiagnostic diagnostic)
             switch (inputVersion)
             {
                 case "2.0":
-                    context.SetReferenceService(new OpenApiV2ReferenceService(rootNode));
+                    context.ReferenceService = new OpenApiV2ReferenceService(rootNode);
                     return OpenApiV2Deserializer.LoadOpenApi(rootNode);
 
                 default:
-                    context.SetReferenceService(new OpenApiV3ReferenceService(rootNode));
+                    context.ReferenceService = new OpenApiV3ReferenceService(rootNode);
                     return OpenApiV3Deserializer.LoadOpenApi(rootNode);
             }
         }
     }
-}
+}

src/Microsoft.OpenApi.Readers/Microsoft.OpenApi.Readers.csproj

@@ -0,0 +1,58 @@
+// ------------------------------------------------------------
+//  Copyright (c) Microsoft Corporation.  All rights reserved.
+//  Licensed under the MIT License (MIT). See LICENSE in the repo root for license information.
+// ------------------------------------------------------------
+
+using System;
+using SharpYaml.Serialization;
+
+namespace Microsoft.OpenApi.Readers.ParseNodes
+{
+    /// <summary>
+    /// Extensions for JSON pointers.
+    /// </summary>
+    public static class JsonPointerExtensions
+    {
+        /// <summary>
+        /// Finds the YAML node that corresponds to this JSON pointer based on the base YAML node.
+        /// </summary>
+        public static YamlNode Find(this JsonPointer currentpointer, YamlNode baseYamlNode)
+        {
+            if (currentpointer.Tokens.Length == 0)
+            {
+                return baseYamlNode;
+            }
+
+            try
+            {
+                var pointer = baseYamlNode;
+                foreach (var token in currentpointer.Tokens)
+                {
+                    var sequence = pointer as YamlSequenceNode;
+
+                    if (sequence != null)
+                    {
+                        pointer = sequence.Children[Convert.ToInt32(token)];
+                    }
+                    else
+                    {
+                        var map = pointer as YamlMappingNode;
+                        if (map != null)
+                        {
+                            if (!map.Children.TryGetValue(new YamlScalarNode(token), out pointer))
+                            {
+                                return null;
+                            }
+                        }
+                    }
+                }
+
+                return pointer;
+            }
+            catch (Exception ex)
+            {
+                throw new ArgumentException("Failed to dereference pointer", ex);
+            }
+        }
+    }
+}

src/Microsoft.OpenApi.Readers/OpenApiStreamReader.cs

@@ -7,11 +7,12 @@
 using System.Collections;
 using System.Collections.Generic;
 using System.Linq;
-using SharpYaml.Schemas;
-using SharpYaml.Serialization;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Exceptions;
 using Microsoft.OpenApi.Interfaces;
+using Microsoft.OpenApi.Models;
+using SharpYaml.Schemas;
+using SharpYaml.Serialization;
 
 namespace Microsoft.OpenApi.Readers.ParseNodes
 {
@@ -28,7 +29,9 @@ public MapNode(ParsingContext context, OpenApiDiagnostic diagnostic, string yaml
         {
         }
 
-        public MapNode(ParsingContext context, OpenApiDiagnostic diagnostic, YamlMappingNode node) : base(context, diagnostic)
+        public MapNode(ParsingContext context, OpenApiDiagnostic diagnostic, YamlMappingNode node) : base(
+            context,
+            diagnostic)
         {
             if (node == null)
             {
@@ -74,7 +77,10 @@ public override Dictionary<string, T> CreateMap<T>(Func<MapNode, T> map)
             return nodes.ToDictionary(k => k.key, v => v.value);
         }
 
-        public override Dictionary<string, T> CreateMapWithReference<T>(string refpointerbase, Func<MapNode, T> map)
+        public override Dictionary<string, T> CreateMapWithReference<T>(
+            ReferenceType referenceType,
+            string refpointerbase,
+            Func<MapNode, T> map)
         {
             var yamlMap = node;
             if (yamlMap == null)
@@ -86,32 +92,12 @@ public override Dictionary<string, T> CreateMapWithReference<T>(string refpointe
                 n => new
                 {
                     key = n.Key.GetScalarValue(),
-                    value = GetReferencedObject<T>(refpointerbase + n.Key.GetScalarValue()) ??
+                    value = GetReferencedObject<T>(referenceType, refpointerbase + n.Key.GetScalarValue()) ??
                     map(new MapNode(Context, Diagnostic, (YamlMappingNode)n.Value))
                 });
             return nodes.ToDictionary(k => k.key, v => v.value);
         }
 
-        public T CreateOrReferenceDomainObject<T>(Func<T> factory) where T : IOpenApiReference
-        {
-            T domainObject;
-            var refPointer = GetReferencePointer(); // What should the DOM of a reference look like?
-            // Duplicated object - poor perf/more memory/unsynchronized changes
-            // Intermediate object - require common base class/client code has to explicitly code for it.
-            // Delegating object - lot of setup work/maintenance/ require full interfaces
-            // **current favourite***Shared object - marker to indicate its a reference/serialization code must serialize as reference everywhere except components.
-            if (refPointer != null)
-            {
-                domainObject = (T)Context.GetReferencedObject(Diagnostic, refPointer);
-            }
-            else
-            {
-                domainObject = factory();
-            }
-
-            return domainObject;
-        }
-
         public override Dictionary<string, T> CreateSimpleMap<T>(Func<ValueNode, T> map)
         {
             var yamlMap = node;
@@ -145,9 +131,13 @@ public override string GetRaw()
             return x.Serialize(node);
         }
 
-        public T GetReferencedObject<T>(string refPointer) where T : IOpenApiReference
+        public T GetReferencedObject<T>(ReferenceType referenceType, string referenceId)
+            where T : IOpenApiReferenceable
         {
-            return (T)Context.GetReferencedObject(Diagnostic, refPointer);
+            return (T)Context.GetReferencedObject(
+                Diagnostic,
+                referenceType,
+                referenceId);
         }
 
         public string GetReferencePointer()

src/Microsoft.OpenApi.Readers/ParseNodes/JsonPointerExtensions.cs

@@ -6,10 +6,11 @@
 using System;
 using System.Collections.Generic;
 using System.Text.RegularExpressions;
-using SharpYaml.Serialization;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Exceptions;
 using Microsoft.OpenApi.Interfaces;
+using Microsoft.OpenApi.Models;
+using SharpYaml.Serialization;
 
 namespace Microsoft.OpenApi.Readers.ParseNodes
 {
@@ -78,8 +79,11 @@ public virtual Dictionary<string, T> CreateMap<T>(Func<MapNode, T> map)
             throw new OpenApiException("Cannot create map");
         }
 
-        public virtual Dictionary<string, T> CreateMapWithReference<T>(string refpointer, Func<MapNode, T> map)
-            where T : class, IOpenApiReference
+        public virtual Dictionary<string, T> CreateMapWithReference<T>(
+            ReferenceType referenceType,
+            string refpointer,
+            Func<MapNode, T> map)
+            where T : class, IOpenApiReferenceable
         {
             throw new OpenApiException("Cannot create map from reference");
         }

src/Microsoft.OpenApi.Readers/ParseNodes/MapNode.cs

@@ -6,9 +6,9 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
-using SharpYaml.Serialization;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Exceptions;
+using SharpYaml.Serialization;
 
 namespace Microsoft.OpenApi.Readers.ParseNodes
 {