Added hostdocument to OpenApiReference

Author: darrelmiller

src/Microsoft.OpenApi.Hidi/OpenApiService.cs

@@ -53,7 +53,7 @@ string filterByCollection
 
             var result = new OpenApiStreamReader(new OpenApiReaderSettings
             {
-                ReferenceResolution = inlineExternal == true ? ReferenceResolutionSetting.ResolveAllReferences : ReferenceResolutionSetting.ResolveLocalReferences,
+                LoadExternalRefs = inlineExternal,
                 RuleSet = ValidationRuleSet.GetDefaultRuleSet(),
                 BaseUrl = new Uri(inputUrl.AbsoluteUri)
             }

src/Microsoft.OpenApi.Readers/OpenApiReaderSettings.cs

@@ -4,15 +4,10 @@
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Readers.Interface;
-using Microsoft.OpenApi.Readers.ParseNodes;
-using Microsoft.OpenApi.Readers.Services;
 using Microsoft.OpenApi.Validations;
 using System;
 using System.Collections.Generic;
 using System.IO;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 
 namespace Microsoft.OpenApi.Readers
 {
@@ -30,7 +25,7 @@ public enum ReferenceResolutionSetting
         /// </summary>
         ResolveLocalReferences,
         /// <summary>
-        /// Not used anymore. Will be removed in v2. Convert all references to references of valid domain objects.
+        /// ResolveAllReferences effectively means load external references. Will be removed in v2. External references are never "resolved".
         /// </summary>
         ResolveAllReferences
     }
@@ -43,8 +38,14 @@ public class OpenApiReaderSettings
         /// <summary>
         /// Indicates how references in the source document should be handled.
         /// </summary>
+        /// <remarks>This setting will be going away in the next major version of this library.  Use GetEffective on model objects to get resolved references.</remarks>
         public ReferenceResolutionSetting ReferenceResolution { get; set; } = ReferenceResolutionSetting.ResolveLocalReferences;
 
+        /// <summary>
+        /// When external references are found, load them into a shared workspace
+        /// </summary>
+        public bool LoadExternalRefs { get; set; } = false;
+
         /// <summary>
         /// Dictionary of parsers for converting extensions into strongly typed classes
         /// </summary>

src/Microsoft.OpenApi.Readers/OpenApiStreamReader.cs

@@ -25,7 +25,7 @@ public OpenApiStreamReader(OpenApiReaderSettings settings = null)
         {
             _settings = settings ?? new OpenApiReaderSettings();
 
-            if(_settings.ReferenceResolution == ReferenceResolutionSetting.ResolveAllReferences 
+            if((_settings.ReferenceResolution == ReferenceResolutionSetting.ResolveAllReferences || _settings.LoadExternalRefs)
                 && _settings.BaseUrl == null)
             {
                 throw new ArgumentException("BaseUrl must be provided to resolve external references.");

src/Microsoft.OpenApi.Readers/OpenApiYamlDocumentReader.cs

@@ -53,6 +53,11 @@ public OpenApiDocument Read(YamlDocument input, out OpenApiDiagnostic diagnostic
                 // Parse the OpenAPI Document
                 document = context.Parse(input);
 
+                if (_settings.LoadExternalRefs)
+                {
+                    throw new InvalidOperationException("Cannot load external refs using the synchronous Read, use ReadAsync instead.");
+                }
+
                 ResolveReferences(diagnostic, document);
             }
             catch (OpenApiException ex)
@@ -88,7 +93,12 @@ public async Task<ReadResult> ReadAsync(YamlDocument input)
                 // Parse the OpenAPI Document
                 document = context.Parse(input);
 
-                await ResolveReferencesAsync(diagnostic, document, _settings.BaseUrl);
+                if (_settings.LoadExternalRefs)
+                {
+                    await LoadExternalRefs(document);
+                }
+
+                ResolveReferences(diagnostic, document);
             }
             catch (OpenApiException ex)
             {
@@ -112,52 +122,28 @@ public async Task<ReadResult> ReadAsync(YamlDocument input)
             };
         }
 
-
-        private void ResolveReferences(OpenApiDiagnostic diagnostic, OpenApiDocument document)
+        private async Task LoadExternalRefs(OpenApiDocument document)
         {
-            // Resolve References if requested
-            switch (_settings.ReferenceResolution)
-            {
-                case ReferenceResolutionSetting.ResolveAllReferences:
-                    throw new ArgumentException("Cannot resolve all references via a synchronous call. Use ReadAsync.");
-                case ReferenceResolutionSetting.ResolveLocalReferences:
-                    var errors = document.ResolveReferences(false);
+            // Create workspace for all documents to live in.
+            var openApiWorkSpace = new OpenApiWorkspace();
 
-                    foreach (var item in errors)
-                    {
-                        diagnostic.Errors.Add(item);
-                    }
-                    break;
-                case ReferenceResolutionSetting.DoNotResolveReferences:
-                    break;
-            }
+            // Load this root document into the workspace
+            var streamLoader = new DefaultStreamLoader(_settings.BaseUrl);
+            var workspaceLoader = new OpenApiWorkspaceLoader(openApiWorkSpace, _settings.CustomExternalLoader ?? streamLoader, _settings);
+            await workspaceLoader.LoadAsync(new OpenApiReference() { ExternalResource = "/" }, document);
         }
 
-        private async Task ResolveReferencesAsync(OpenApiDiagnostic diagnostic, OpenApiDocument document, Uri baseUrl)
+        private void ResolveReferences(OpenApiDiagnostic diagnostic, OpenApiDocument document)
         {
             List<OpenApiError> errors = new List<OpenApiError>();
 
             // Resolve References if requested
             switch (_settings.ReferenceResolution)
             {
                 case ReferenceResolutionSetting.ResolveAllReferences:
-
-                    // Create workspace for all documents to live in.
-                    var openApiWorkSpace = new OpenApiWorkspace();
-
-                    // Load this root document into the workspace
-                    var streamLoader = new DefaultStreamLoader(baseUrl);
-                    var workspaceLoader = new OpenApiWorkspaceLoader(openApiWorkSpace, _settings.CustomExternalLoader ?? streamLoader, _settings);
-                    await workspaceLoader.LoadAsync(new OpenApiReference() { ExternalResource = "/" }, document);
-
-                    // Resolve all references in all the documents loaded into the OpenApiWorkspace
-                    foreach (var doc in openApiWorkSpace.Documents)
-                    {
-                        errors.AddRange(doc.ResolveReferences(true));
-                    }
-                    break;
+                    throw new ArgumentException("Resolving external references is not supported");
                 case ReferenceResolutionSetting.ResolveLocalReferences:
-                    errors.AddRange(document.ResolveReferences(false));
+                    errors.AddRange(document.ResolveReferences());
                     break;
                 case ReferenceResolutionSetting.DoNotResolveReferences:
                     break;

src/Microsoft.OpenApi/Interfaces/IEffective.cs

@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. 
+
+using Microsoft.OpenApi.Models;
+
+namespace Microsoft.OpenApi.Interfaces
+{
+    /// <summary>
+    /// OpenApiElements that implement IEffective indicate that their description is not self-contained.
+    /// External elements affect the effective description.
+    /// </summary>
+    /// <remarks>Currently this will only be used for accessing external references.  
+    /// In the next major version, this will be the approach accessing all referenced elements. 
+    /// This will enable us to support merging properties that are peers of the $ref  </remarks>
+    /// <typeparam name="T">Type of OpenApi Element that is being referenced.</typeparam>
+    public interface IEffective<T>  where T : class,IOpenApiElement
+    {
+        /// <summary>
+        /// Returns a calculated and cloned version of the element.
+        /// </summary>
+        T GetEffective(OpenApiDocument document);
+    }
+}

src/Microsoft.OpenApi/Interfaces/IOpenApiReferenceable.cs

@@ -31,5 +31,6 @@ public interface IOpenApiReferenceable : IOpenApiSerializable
         /// Serialize to OpenAPI V2 document without using reference.
         /// </summary>
         void SerializeAsV2WithoutReference(IOpenApiWriter writer);
+
     }
 }

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -321,27 +321,37 @@ private static void WriteHostInfoV2(IOpenApiWriter writer, IList<OpenApiServer>
         /// <summary>
         /// Walk the OpenApiDocument and resolve unresolved references
         /// </summary>
-        /// <param name="useExternal">Indicates if external references should be resolved.  Document needs to reference a workspace for this to be possible.</param>
-        public IEnumerable<OpenApiError> ResolveReferences(bool useExternal = false)
+        /// <remarks>
+        /// This method will be replaced by a LoadExternalReferences in the next major update to this library.
+        /// Resolving references at load time is going to go away.
+        /// </remarks>
+        public IEnumerable<OpenApiError> ResolveReferences()
         {
-            var resolver = new OpenApiReferenceResolver(this, useExternal);
+            var resolver = new OpenApiReferenceResolver(this, false);
             var walker = new OpenApiWalker(resolver);
             walker.Walk(this);
             return resolver.Errors;
         }
 
-            /// <summary>
-            /// Load the referenced <see cref="IOpenApiReferenceable"/> object from a <see cref="OpenApiReference"/> object
-            /// </summary>
-            public IOpenApiReferenceable ResolveReference(OpenApiReference reference)
+        /// <summary>
+        /// Load the referenced <see cref="IOpenApiReferenceable"/> object from a <see cref="OpenApiReference"/> object
+        /// </summary>
+        internal T ResolveReferenceTo<T>(OpenApiReference reference) where T : class, IOpenApiReferenceable
+        {
+            if (reference.IsExternal)
             {
-                return ResolveReference(reference, false);
+                return ResolveReference(reference, true) as T;
             }
+            else
+            {
+                return ResolveReference(reference, false) as T;
+            }
+        }
 
-            /// <summary>
-            /// Load the referenced <see cref="IOpenApiReferenceable"/> object from a <see cref="OpenApiReference"/> object
-            /// </summary>
-            public IOpenApiReferenceable ResolveReference(OpenApiReference reference, bool useExternal)
+        /// <summary>
+        /// Load the referenced <see cref="IOpenApiReferenceable"/> object from a <see cref="OpenApiReference"/> object
+        /// </summary>
+        internal IOpenApiReferenceable ResolveReference(OpenApiReference reference, bool useExternal)
         {
             if (reference == null)
             {

src/Microsoft.OpenApi/Models/OpenApiParameter.cs

@@ -12,7 +12,7 @@ namespace Microsoft.OpenApi.Models
     /// <summary>
     /// Parameter Object.
     /// </summary>
-    public class OpenApiParameter : IOpenApiSerializable, IOpenApiReferenceable, IOpenApiExtensible
+    public class OpenApiParameter : IOpenApiSerializable, IOpenApiReferenceable, IEffective<OpenApiParameter>, IOpenApiExtensible
     {
         private bool? _explode;
 
@@ -332,6 +332,18 @@ public void SerializeAsV2WithoutReference(IOpenApiWriter writer)
 
             writer.WriteEndObject();
         }
+
+        public OpenApiParameter GetEffective(OpenApiDocument doc)
+        {
+            if (this.Reference != null)
+            {
+                return doc.ResolveReferenceTo<OpenApiParameter>(this.Reference);
+            }
+            else
+            {
+                return this;
+            }
+        }
     }
 
     /// <summary>

src/Microsoft.OpenApi/Models/OpenApiReference.cs

@@ -45,6 +45,11 @@ public class OpenApiReference : IOpenApiSerializable
         /// </summary>
         public bool IsLocal => ExternalResource == null;
 
+        /// <summary>
+        /// The OpenApiDocument that is hosting the OpenApiReference instance. This is used to enable dereferencing the reference.
+        /// </summary>
+        public OpenApiDocument HostDocument { get; set; } = null;
+
         /// <summary>
         /// Gets the full reference string for v3.0.
         /// </summary>

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -11,7 +11,7 @@ namespace Microsoft.OpenApi.Models
     /// <summary>
     /// Schema Object.
     /// </summary>
-    public class OpenApiSchema : IOpenApiSerializable, IOpenApiReferenceable, IOpenApiExtensible
+    public class OpenApiSchema : IOpenApiSerializable, IOpenApiReferenceable, IEffective<OpenApiSchema>, IOpenApiExtensible
     {
         /// <summary>
         /// Follow JSON Schema definition. Short text providing information about the data.
@@ -252,13 +252,21 @@ public void SerializeAsV3(IOpenApiWriter writer)
             }
 
             var settings = writer.GetSettings();
+            var target = this;
 
             if (Reference != null)
             {
                 if (!settings.ShouldInlineReference(Reference))
                 {
                     Reference.SerializeAsV3(writer);
                     return;
+                } 
+                else
+                {
+                    if (Reference.IsExternal)  // Temporary until v2
+                    {
+                        target = this.GetEffective(Reference.HostDocument);
+                    }
                 }
 
                 // If Loop is detected then just Serialize as a reference.
@@ -270,7 +278,7 @@ public void SerializeAsV3(IOpenApiWriter writer)
                 }
             }
 
-            SerializeAsV3WithoutReference(writer);
+            target.SerializeAsV3WithoutReference(writer);
 
             if (Reference != null)
             {
@@ -283,6 +291,7 @@ public void SerializeAsV3(IOpenApiWriter writer)
         /// </summary>
         public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
         {
+
             writer.WriteStartObject();
 
             // title
@@ -666,5 +675,16 @@ internal void WriteAsSchemaProperties(
             // extensions
             writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi2_0);
         }
+
+        public OpenApiSchema GetEffective(OpenApiDocument doc)
+        {
+            if (this.Reference != null)
+            {
+                return doc.ResolveReferenceTo<OpenApiSchema>(this.Reference);
+            } else
+            {
+                return this;
+            }
+        }
     }
 }