Merge pull request #161 from Microsoft/dm/context-refactor

Refactoring to simplify interactions around ParsingContext

Author: darrelmiller

src/Microsoft.OpenApi.Readers/ReferenceServices/IOpenApiReferenceService.cs renamed to src/Microsoft.OpenApi.Readers/Interface/IOpenApiVersionService.cs

@@ -1,19 +1,22 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
+using System;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Readers.ParseNodes;
 
-namespace Microsoft.OpenApi.Readers.ReferenceServices
+namespace Microsoft.OpenApi.Readers.Interface
 {
     /// <summary>
-    /// Interface for Open API Reference parse.
+    /// Interface to a version specific parsing implementations.
     /// </summary>
-    public interface IOpenApiReferenceService
+    internal interface IOpenApiVersionService
     {
         /// <summary>
         /// Load the referenced <see cref="IOpenApiReferenceable"/> object from a <see cref="OpenApiReference"/> object
         /// </summary>
+        /// <param name="context">Instance of ParsingContext to use for retrieving references.</param>
         /// <param name="reference">The <see cref="OpenApiReference"/> object.</param>
         /// <param name="referencedObject">The object that is being referenced.</param>
         /// <returns>
@@ -22,7 +25,7 @@ public interface IOpenApiReferenceService
         /// a new tag will be returned in the outer parameter and the return value will be false.
         /// If reference is null, no object will be returned and the return value will be false.
         /// </returns>
-        bool TryLoadReference(OpenApiReference reference, out IOpenApiReferenceable referencedObject);
+        bool TryLoadReference(ParsingContext context, OpenApiReference reference, out IOpenApiReferenceable referencedObject);
 
         /// <summary>
         /// Parse the string to a <see cref="OpenApiReference"/> object.
@@ -31,5 +34,17 @@ public interface IOpenApiReferenceService
         /// <param name="type">The type of the reference.</param>
         /// <returns>The <see cref="OpenApiReference"/> object or null.</returns>
         OpenApiReference ConvertToOpenApiReference(string reference, ReferenceType? type);
+
+        /// <summary>
+        /// Function that converts a MapNode into a Tag object in a version specific way
+        /// </summary>
+        Func<MapNode, OpenApiTag> TagLoader { get; }
+
+        /// <summary>
+        /// Converts a generic RootNode instance into a strongly typed OpenApiDocument
+        /// </summary>
+        /// <param name="rootNode">RootNode containing the information to be converted into an OpenAPI Document</param>
+        /// <returns>Instance of OpenApiDocument populated with data from rootNode</returns>
+        OpenApiDocument LoadDocument(RootNode rootNode);
     }
 }

src/Microsoft.OpenApi.Readers/OpenApiStreamReader.cs

@@ -5,10 +5,6 @@
 using System.Linq;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.Interface;
-using Microsoft.OpenApi.Readers.ParseNodes;
-using Microsoft.OpenApi.Readers.ReferenceServices;
-using Microsoft.OpenApi.Readers.V2;
-using Microsoft.OpenApi.Readers.V3;
 using SharpYaml;
 using SharpYaml.Serialization;
 
@@ -19,69 +15,48 @@ namespace Microsoft.OpenApi.Readers
     /// </summary>
     public class OpenApiStreamReader : IOpenApiReader<Stream, OpenApiDiagnostic>
     {
-        /// <summary>
-        /// Gets the version of the Open API document.
-        /// </summary>
-        private static string GetVersion(RootNode rootNode)
-        {
-            var versionNode = rootNode.Find(new JsonPointer("/openapi"));
-
-            if (versionNode != null)
-            {
-                return versionNode.GetScalarValue();
-            }
-
-            versionNode = rootNode.Find(new JsonPointer("/swagger"));
-
-            return versionNode?.GetScalarValue();
-        }
 
         /// <summary>
         /// Reads the stream input and parses it into an Open API document.
         /// </summary>
+        /// <param name="input">Stream containing OpenAPI description to parse.</param>
+        /// <param name="diagnostic">Returns diagnostic object containing errors detected during parsing</param>
+        /// <returns>Instance of newly created OpenApiDocument</returns>
         public OpenApiDocument Read(Stream input, out OpenApiDiagnostic diagnostic)
         {
-            RootNode rootNode;
-            var context = new ParsingContext();
+            ParsingContext context;
+            YamlDocument yamlDocument;
             diagnostic = new OpenApiDiagnostic();
 
             try
             {
-                using (var streamReader = new StreamReader(input))
-                {
-                    var yamlStream = new YamlStream();
-                    yamlStream.Load(streamReader);
-
-                    var yamlDocument = yamlStream.Documents.First();
-                    rootNode = new RootNode(context, diagnostic, yamlDocument);
-                }
+                yamlDocument = LoadYamlDocument(input);
             }
             catch (SyntaxErrorException ex)
             {
                 diagnostic.Errors.Add(new OpenApiError(string.Empty, ex.Message));
-
                 return new OpenApiDocument();
             }
 
-            var inputVersion = GetVersion(rootNode);
+            context = new ParsingContext();
+            return context.Parse(yamlDocument, diagnostic);
+        }
 
-            if ( inputVersion == "2.0")
-            {
-                context.ReferenceService = new OpenApiV2ReferenceService(rootNode);
-                return OpenApiV2Deserializer.LoadOpenApi(rootNode);
-            }
-            else if (inputVersion.StartsWith("3.0."))
-            {
-                context.ReferenceService = new OpenApiV3ReferenceService(rootNode);
-                return OpenApiV3Deserializer.LoadOpenApi(rootNode);
-            }
-            else
+        /// <summary>
+        /// Helper method to turn streams into YamlDocument
+        /// </summary>
+        /// <param name="input">Stream containing YAML formatted text</param>
+        /// <returns>Instance of a YamlDocument</returns>
+        internal static YamlDocument LoadYamlDocument(Stream input)
+        {
+            YamlDocument yamlDocument;
+            using (var streamReader = new StreamReader(input))
             {
-                // If version number is not recognizable,
-                // our best effort will try to deserialize the document to V3.
-                context.ReferenceService = new OpenApiV3ReferenceService(rootNode);
-                return OpenApiV3Deserializer.LoadOpenApi(rootNode);
+                var yamlStream = new YamlStream();
+                yamlStream.Load(streamReader);
+                yamlDocument = yamlStream.Documents.First();
             }
+            return yamlDocument;
         }
     }
 }

src/Microsoft.OpenApi.Readers/ParsingContext.cs

@@ -1,30 +1,112 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
+using System;
 using System.Collections.Generic;
 using System.Linq;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Models;
-using Microsoft.OpenApi.Readers.ReferenceServices;
+using Microsoft.OpenApi.Readers.Interface;
+using Microsoft.OpenApi.Readers.ParseNodes;
+using Microsoft.OpenApi.Readers.V2;
+using Microsoft.OpenApi.Readers.V3;
+using SharpYaml.Serialization;
 
 namespace Microsoft.OpenApi.Readers
 {
     /// <summary>
-    /// Parsing context.
+    /// The Parsing Context holds temporary state needed whilst parsing an OpenAPI Document
     /// </summary>
     public class ParsingContext
     {
         private readonly Stack<string> _currentLocation = new Stack<string>();
+        private readonly Dictionary<string, IOpenApiReferenceable> _referenceStore = new Dictionary<string, IOpenApiReferenceable>();
+        private readonly Dictionary<string, object> _tempStorage = new Dictionary<string, object>();
+        private IOpenApiVersionService _versionService;
+        internal RootNode RootNode { get; set; }
+        internal List<OpenApiTag> Tags { get; private set; } = new List<OpenApiTag>();
 
-        private readonly Dictionary<string, IOpenApiReferenceable> _referenceStore =
-            new Dictionary<string, IOpenApiReferenceable>();
 
-        private readonly Dictionary<string, object> _tempStorage = new Dictionary<string, object>();
+        /// <summary>
+        /// Initiates the parsing process.  Not thread safe and should only be called once on a parsing context
+        /// </summary>
+        /// <param name="yamlDocument"></param>
+        /// <param name="diagnostic"></param>
+        /// <returns>An OpenApiDocument populated based on the passed yamlDocument </returns>
+        internal OpenApiDocument Parse(YamlDocument yamlDocument, OpenApiDiagnostic diagnostic)
+        {
+            RootNode = new RootNode(this, diagnostic, yamlDocument);
+
+            var inputVersion = GetVersion(RootNode);
+
+            OpenApiDocument doc;
+
+            if (inputVersion == "2.0")
+            {
+                VersionService = new OpenApiV2VersionService();
+                doc = this.VersionService.LoadDocument(this.RootNode);
+            }
+            else if (inputVersion.StartsWith("3.0."))
+            {
+                this.VersionService = new OpenApiV3VersionService();
+                doc = this.VersionService.LoadDocument(this.RootNode);
+            }
+            else
+            {
+                // If version number is not recognizable,
+                // our best effort will try to deserialize the document to V3.
+                this.VersionService = new OpenApiV3VersionService();
+                doc = this.VersionService.LoadDocument(this.RootNode);
+            }
+            return doc;
+        }
 
         /// <summary>
-        /// Reference service.
+        /// Gets the version of the Open API document.
         /// </summary>
-        internal IOpenApiReferenceService ReferenceService { get; set; }
+        private static string GetVersion(RootNode rootNode)
+        {
+            var versionNode = rootNode.Find(new JsonPointer("/openapi"));
+
+            if (versionNode != null)
+            {
+                return versionNode.GetScalarValue();
+            }
+
+            versionNode = rootNode.Find(new JsonPointer("/swagger"));
+
+            return versionNode?.GetScalarValue();
+        }
+
+        private void ComputeTags(List<OpenApiTag> tags, Func<MapNode,OpenApiTag> loadTag )
+        {
+            // Precompute the tags array so that each tag reference does not require a new deserialization.
+            var tagListPointer = new JsonPointer("#/tags");
+
+            var tagListNode = RootNode.Find(tagListPointer);
+
+            if (tagListNode != null && tagListNode is ListNode)
+            {
+                var tagListNodeAsListNode = (ListNode)tagListNode;
+                tags.AddRange(tagListNodeAsListNode.CreateList(loadTag));
+            }
+        }
+
+        /// <summary>
+        /// Service providing all Version specific conversion functions
+        /// </summary>
+        internal IOpenApiVersionService VersionService
+        {
+            get
+            {
+                return _versionService;
+            }
+            set
+            {
+                _versionService = value;
+                ComputeTags(Tags, VersionService.TagLoader);
+            }
+        }
 
         /// <summary>
         /// End the current object.
@@ -58,9 +140,9 @@ public IOpenApiReferenceable GetReferencedObject(
                 return referencedObject;
             }
 
-            var reference = ReferenceService.ConvertToOpenApiReference(referenceString, referenceType);
+            var reference = VersionService.ConvertToOpenApiReference(referenceString, referenceType);
 
-            var isReferencedObjectFound = ReferenceService.TryLoadReference(reference, out referencedObject);
+            var isReferencedObjectFound = VersionService.TryLoadReference(this, reference, out referencedObject);
 
             if (isReferencedObjectFound)
             {

src/Microsoft.OpenApi.Readers/ReferenceServices/OpenApiV2ReferenceService.cs renamed to src/Microsoft.OpenApi.Readers/V2/OpenApiV2VersionService.cs

@@ -2,50 +2,30 @@
 // Licensed under the MIT license. 
 
 using System;
-using System.Collections.Generic;
 using Microsoft.OpenApi.Exceptions;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Readers.Interface;
 using Microsoft.OpenApi.Readers.ParseNodes;
 using Microsoft.OpenApi.Readers.Properties;
-using Microsoft.OpenApi.Readers.V2;
-using Microsoft.OpenApi.Readers.V3;
 
-namespace Microsoft.OpenApi.Readers.ReferenceServices
+
+namespace Microsoft.OpenApi.Readers.V2
 {
     /// <summary>
-    /// The reference service for the Open API V2.0.
+    /// The version specific implementations for OpenAPI V2.0.
     /// </summary>
-    internal class OpenApiV2ReferenceService : IOpenApiReferenceService
+    internal class OpenApiV2VersionService : IOpenApiVersionService
     {
-        private readonly RootNode _rootNode;
-
-        private readonly List<OpenApiTag> _tags = new List<OpenApiTag>();
-
         /// <summary>
-        /// Initializes a new instance of the <see cref="OpenApiV2ReferenceService"/> class.
+        /// Return a function that converts a MapNode into a V2 OpenApiTag
         /// </summary>
-        /// <param name="rootNode">The root node.</param>
-        public OpenApiV2ReferenceService(RootNode rootNode)
-        {
-            _rootNode = rootNode ?? throw new ArgumentNullException(nameof(rootNode));
-
-            // Precompute the tags array so that each tag reference does not require a new deserialization.
-            var tagListPointer = new JsonPointer("#/tags");
-
-            var tagListNode = _rootNode.Find(tagListPointer);
-
-            if (tagListNode != null && tagListNode is ListNode)
-            {
-                var tagListNodeAsListNode = (ListNode)tagListNode;
-                _tags.AddRange(tagListNodeAsListNode.CreateList(OpenApiV3Deserializer.LoadTag));
-            }
-        }
+        public Func<MapNode, OpenApiTag> TagLoader => OpenApiV2Deserializer.LoadTag;
 
         /// <summary>
         /// Load the referenced <see cref="IOpenApiReferenceable"/> object from a <see cref="OpenApiReference"/> object
         /// </summary>
-        public bool TryLoadReference(OpenApiReference reference, out IOpenApiReferenceable referencedObject)
+        public bool TryLoadReference(ParsingContext context, OpenApiReference reference, out IOpenApiReferenceable referencedObject)
         {
             referencedObject = null;
 
@@ -68,7 +48,7 @@ public bool TryLoadReference(OpenApiReference reference, out IOpenApiReferenceab
             // Special case for Tag
             if (reference.Type == ReferenceType.Tag)
             {
-                foreach (var tag in _tags)
+                foreach (var tag in context.Tags)
                 {
                     if (tag.Name == reference.Id)
                     {
@@ -84,7 +64,7 @@ public bool TryLoadReference(OpenApiReference reference, out IOpenApiReferenceab
             var jsonPointer =
                 new JsonPointer("#/" + GetReferenceTypeV2Name(reference.Type.Value) + "/" + reference.Id);
 
-            var node = _rootNode.Find(jsonPointer);
+            var node = context.RootNode.Find(jsonPointer);
 
             switch (reference.Type)
             {
@@ -116,7 +96,7 @@ public bool TryLoadReference(OpenApiReference reference, out IOpenApiReferenceab
             return true;
         }
 
-        private OpenApiReference ParseLocalReference(string localReference)
+        private static OpenApiReference ParseLocalReference(string localReference)
         {
             if (string.IsNullOrWhiteSpace(localReference))
             {
@@ -244,5 +224,10 @@ public OpenApiReference ConvertToOpenApiReference(string reference, ReferenceTyp
 
             throw new OpenApiException(string.Format(SRResource.ReferenceHasInvalidFormat, reference));
         }
+
+        public OpenApiDocument LoadDocument(RootNode rootNode)
+        {
+            return OpenApiV2Deserializer.LoadOpenApi(rootNode);
+        }
     }
 }