Creates derived reference objects for on-demand reference resolution (#1290)

* Add reference classes

* Add serialization methods to reference classes

* Modify access modifiers

* Add header reference class

* Use Target property instead of this

* Make Reference property readonly; add constructors to get reference value

* Add new constructor

* Add reference tests

* Add Tag reference tests

* Update tests, method signatures and properties

* Revert access modifiers

* Update methods

* Update tests

* Update tests

* Add externalResource parameter to constructors

This is to help capture externally referenced resources

* Add tests for external reference resolution

* Add description field

* Update teg reference serializer and tests

* Update PublicApi

* Fix broken tests

* Add guard clause for potentially null Target value

* Check for null or empty for strings

* Use local field for getter and setter

* Additional check for null or empty for string properties

Author: irvinesunday

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

@@ -3,7 +3,6 @@
 
 using System;
 using System.Collections.Generic;
-using System.Text.Json.Nodes;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Models;
 

src/Microsoft.OpenApi/Models/OpenApiCallback.cs

@@ -7,7 +7,6 @@
 using Microsoft.OpenApi.Expressions;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Writers;
-using static Microsoft.OpenApi.Extensions.OpenApiSerializableExtensions;
 
 namespace Microsoft.OpenApi.Models
 {
@@ -19,13 +18,13 @@ public class OpenApiCallback : IOpenApiSerializable, IOpenApiReferenceable, IOpe
         /// <summary>
         /// A Path Item Object used to define a callback request and expected responses.
         /// </summary>
-        public Dictionary<RuntimeExpression, OpenApiPathItem> PathItems { get; set; }
+        public virtual Dictionary<RuntimeExpression, OpenApiPathItem> PathItems { get; set; }
             = new Dictionary<RuntimeExpression, OpenApiPathItem>();
 
         /// <summary>
         /// Indicates if object is populated with data or is just a reference to the data
         /// </summary>
-        public bool UnresolvedReference { get; set; }
+        public virtual bool UnresolvedReference { get; set; }
 
         /// <summary>
         /// Reference pointer.
@@ -35,7 +34,7 @@ public class OpenApiCallback : IOpenApiSerializable, IOpenApiReferenceable, IOpe
         /// <summary>
         /// This object MAY be extended with Specification Extensions.
         /// </summary>
-        public IDictionary<string, IOpenApiExtension> Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
+        public virtual IDictionary<string, IOpenApiExtension> Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
 
         /// <summary>
         /// Parameter-less constructor
@@ -83,7 +82,7 @@ public void AddPathItem(RuntimeExpression expression, OpenApiPathItem pathItem)
         /// </summary>
         /// <param name="writer"></param>
         /// <exception cref="System.NotImplementedException"></exception>
-        public void SerializeAsV31(IOpenApiWriter writer)
+        public virtual void SerializeAsV31(IOpenApiWriter writer)
         {
             SerializeInternal(writer, (writer, element) => element.SerializeAsV31(writer),
                 (writer, referenceElement) => referenceElement.SerializeAsV31WithoutReference(writer));
@@ -92,7 +91,7 @@ public void SerializeAsV31(IOpenApiWriter writer)
         /// <summary>
         /// Serialize <see cref="OpenApiCallback"/> to Open Api v3.0
         /// </summary>
-        public void SerializeAsV3(IOpenApiWriter writer)
+        public virtual void SerializeAsV3(IOpenApiWriter writer)
         {
             SerializeInternal(writer, (writer, element) => element.SerializeAsV3(writer), 
                 (writer, referenceElement) => referenceElement.SerializeAsV3WithoutReference(writer));
@@ -111,7 +110,7 @@ private void SerializeInternal(IOpenApiWriter writer,
             writer = writer ?? throw Error.ArgumentNull(nameof(writer));
 
             var target = this;
-
+            
             if (Reference != null)
             {
                 if (!writer.GetSettings().ShouldInlineReference(Reference))
@@ -124,6 +123,7 @@ private void SerializeInternal(IOpenApiWriter writer,
                     target = GetEffective(Reference.HostDocument);
                 }
             }
+            
             action(writer, target);
         }
 
@@ -134,9 +134,9 @@ private void SerializeInternal(IOpenApiWriter writer,
         /// <returns>OpenApiCallback</returns>
         public OpenApiCallback GetEffective(OpenApiDocument doc)
         {
-            if (this.Reference != null)
+            if (Reference != null)
             {
-                return doc.ResolveReferenceTo<OpenApiCallback>(this.Reference);
+                return doc.ResolveReferenceTo<OpenApiCallback>(Reference);
             }
             else
             {
@@ -147,7 +147,7 @@ public OpenApiCallback GetEffective(OpenApiDocument doc)
         /// <summary>
         /// Serialize to OpenAPI V31 document without using reference.
         /// </summary>
-        public void SerializeAsV31WithoutReference(IOpenApiWriter writer)
+        public virtual void SerializeAsV31WithoutReference(IOpenApiWriter writer)
         {
             SerializeInternalWithoutReference(writer, OpenApiSpecVersion.OpenApi3_1, 
                 (writer, element) => element.SerializeAsV31(writer));
@@ -156,13 +156,13 @@ public void SerializeAsV31WithoutReference(IOpenApiWriter writer)
         /// <summary>
         /// Serialize to OpenAPI V3 document without using reference.
         /// </summary>
-        public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
+        public virtual void SerializeAsV3WithoutReference(IOpenApiWriter writer)
         {
             SerializeInternalWithoutReference(writer, OpenApiSpecVersion.OpenApi3_0, 
                 (writer, element) => element.SerializeAsV3(writer));
         }        
-
-        private void SerializeInternalWithoutReference(IOpenApiWriter writer, OpenApiSpecVersion version, 
+        
+        internal void SerializeInternalWithoutReference(IOpenApiWriter writer, OpenApiSpecVersion version, 
             Action<IOpenApiWriter, IOpenApiSerializable> callback)
         {
             writer.WriteStartObject();

src/Microsoft.OpenApi/Models/OpenApiComponents.cs

@@ -16,60 +16,60 @@ public class OpenApiComponents : IOpenApiSerializable, IOpenApiExtensible
         /// <summary>
         /// An object to hold reusable <see cref="OpenApiSchema"/> Objects.
         /// </summary>
-        public IDictionary<string, OpenApiSchema> Schemas { get; set; } = new Dictionary<string, OpenApiSchema>();
+        public virtual IDictionary<string, OpenApiSchema> Schemas { get; set; } = new Dictionary<string, OpenApiSchema>();
 
         /// <summary>
         /// An object to hold reusable <see cref="OpenApiResponse"/> Objects.
         /// </summary>
-        public IDictionary<string, OpenApiResponse> Responses { get; set; } = new Dictionary<string, OpenApiResponse>();
+        public virtual IDictionary<string, OpenApiResponse> Responses { get; set; } = new Dictionary<string, OpenApiResponse>();
 
         /// <summary>
         /// An object to hold reusable <see cref="OpenApiParameter"/> Objects.
         /// </summary>
-        public IDictionary<string, OpenApiParameter> Parameters { get; set; } =
+        public virtual IDictionary<string, OpenApiParameter> Parameters { get; set; } =
             new Dictionary<string, OpenApiParameter>();
 
         /// <summary>
         /// An object to hold reusable <see cref="OpenApiExample"/> Objects.
         /// </summary>
-        public IDictionary<string, OpenApiExample> Examples { get; set; } = new Dictionary<string, OpenApiExample>();
+        public virtual IDictionary<string, OpenApiExample> Examples { get; set; } = new Dictionary<string, OpenApiExample>();
 
         /// <summary>
         /// An object to hold reusable <see cref="OpenApiRequestBody"/> Objects.
         /// </summary>
-        public IDictionary<string, OpenApiRequestBody> RequestBodies { get; set; } =
+        public virtual IDictionary<string, OpenApiRequestBody> RequestBodies { get; set; } =
             new Dictionary<string, OpenApiRequestBody>();
 
         /// <summary>
         /// An object to hold reusable <see cref="OpenApiHeader"/> Objects.
         /// </summary>
-        public IDictionary<string, OpenApiHeader> Headers { get; set; } = new Dictionary<string, OpenApiHeader>();
+        public virtual IDictionary<string, OpenApiHeader> Headers { get; set; } = new Dictionary<string, OpenApiHeader>();
 
         /// <summary>
         /// An object to hold reusable <see cref="OpenApiSecurityScheme"/> Objects.
         /// </summary>
-        public IDictionary<string, OpenApiSecurityScheme> SecuritySchemes { get; set; } =
+        public virtual IDictionary<string, OpenApiSecurityScheme> SecuritySchemes { get; set; } =
             new Dictionary<string, OpenApiSecurityScheme>();
 
         /// <summary>
         /// An object to hold reusable <see cref="OpenApiLink"/> Objects.
         /// </summary>
-        public IDictionary<string, OpenApiLink> Links { get; set; } = new Dictionary<string, OpenApiLink>();
+        public virtual IDictionary<string, OpenApiLink> Links { get; set; } = new Dictionary<string, OpenApiLink>();
 
         /// <summary>
         /// An object to hold reusable <see cref="OpenApiCallback"/> Objects.
         /// </summary>
-        public IDictionary<string, OpenApiCallback> Callbacks { get; set; } = new Dictionary<string, OpenApiCallback>();
+        public virtual IDictionary<string, OpenApiCallback> Callbacks { get; set; } = new Dictionary<string, OpenApiCallback>();
 
         /// <summary>
         /// An object to hold reusable <see cref="OpenApiPathItem"/> Object.
         /// </summary>
-        public IDictionary<string, OpenApiPathItem> PathItems { get; set; } = new Dictionary<string, OpenApiPathItem>();
+        public virtual IDictionary<string, OpenApiPathItem> PathItems { get; set; } = new Dictionary<string, OpenApiPathItem>();
 
         /// <summary>
         /// This object MAY be extended with Specification Extensions.
         /// </summary>
-        public IDictionary<string, IOpenApiExtension> Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
+        public virtual IDictionary<string, IOpenApiExtension> Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
 
         /// <summary>
         /// Parameter-less constructor

src/Microsoft.OpenApi/Models/OpenApiContact.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;

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -12,7 +12,6 @@
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Services;
 using Microsoft.OpenApi.Writers;
-using static Microsoft.OpenApi.Extensions.OpenApiSerializableExtensions;
 
 namespace Microsoft.OpenApi.Models
 {

src/Microsoft.OpenApi/Models/OpenApiExample.cs

@@ -18,43 +18,43 @@ public class OpenApiExample : IOpenApiSerializable, IOpenApiReferenceable, IOpen
         /// <summary>
         /// Short description for the example.
         /// </summary>
-        public string Summary { get; set; }
+        public virtual string Summary { get; set; }
 
         /// <summary>
         /// Long description for the example.
         /// CommonMark syntax MAY be used for rich text representation.
         /// </summary>
-        public string Description { get; set; }
+        public virtual string Description { get; set; }
 
         /// <summary>
         /// Embedded literal example. The value field and externalValue field are mutually
         /// exclusive. To represent examples of media types that cannot naturally represented
         /// in JSON or YAML, use a string value to contain the example, escaping where necessary.
         /// </summary>
-        public OpenApiAny Value { get; set; }
+        public virtual OpenApiAny Value { get; set; }
 
         /// <summary>
         /// A URL that points to the literal example.
         /// This provides the capability to reference examples that cannot easily be
         /// included in JSON or YAML documents.
         /// The value field and externalValue field are mutually exclusive.
         /// </summary>
-        public string ExternalValue { get; set; }
+        public virtual string ExternalValue { get; set; }
 
         /// <summary>
         /// This object MAY be extended with Specification Extensions.
         /// </summary>
-        public IDictionary<string, IOpenApiExtension> Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
+        public virtual IDictionary<string, IOpenApiExtension> Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
 
         /// <summary>
         /// Reference object.
         /// </summary>
-        public OpenApiReference Reference { get; set; }
+        public virtual OpenApiReference Reference { get; set; }
 
         /// <summary>
         /// Indicates object is a placeholder reference to an actual object and does not contain valid data.
         /// </summary>
-        public bool UnresolvedReference { get; set; } = false;
+        public virtual bool UnresolvedReference { get; set; } = false;
 
         /// <summary>
         /// Parameter-less constructor
@@ -79,7 +79,7 @@ public OpenApiExample(OpenApiExample example)
         /// Serialize <see cref="OpenApiExample"/> to Open Api v3.1
         /// </summary>
         /// <param name="writer"></param>
-        public void SerializeAsV31(IOpenApiWriter writer)
+        public virtual void SerializeAsV31(IOpenApiWriter writer)
         {
             SerializeInternal(writer, (writer, element) => element.SerializeAsV31(writer), 
                 (writer, element) => element.SerializeAsV31WithoutReference(writer));
@@ -89,13 +89,13 @@ public void SerializeAsV31(IOpenApiWriter writer)
         /// Serialize <see cref="OpenApiExample"/> to Open Api v3.0
         /// </summary>
         /// <param name="writer"></param>
-        public void SerializeAsV3(IOpenApiWriter writer)
+        public virtual void SerializeAsV3(IOpenApiWriter writer)
         {
             SerializeInternal(writer, (writer, element) => element.SerializeAsV3(writer), 
                 (writer, element) => element.SerializeAsV3WithoutReference(writer));
         }
 
-        private void SerializeInternal(IOpenApiWriter writer, Action<IOpenApiWriter, IOpenApiSerializable> callback,
+        internal virtual void SerializeInternal(IOpenApiWriter writer, Action<IOpenApiWriter, IOpenApiSerializable> callback,
             Action<IOpenApiWriter, IOpenApiReferenceable> action)
         {
             writer = writer ?? throw Error.ArgumentNull(nameof(writer));
@@ -124,7 +124,7 @@ private void SerializeInternal(IOpenApiWriter writer, Action<IOpenApiWriter, IOp
         /// <returns>OpenApiExample</returns>
         public OpenApiExample GetEffective(OpenApiDocument doc)
         {
-            if (this.Reference != null)
+            if (Reference != null)
             {
                 return doc.ResolveReferenceTo<OpenApiExample>(this.Reference);
             }
@@ -137,20 +137,20 @@ public OpenApiExample GetEffective(OpenApiDocument doc)
         /// <summary>
         /// Serialize to OpenAPI V31 example without using reference.
         /// </summary>
-        public void SerializeAsV31WithoutReference(IOpenApiWriter writer) 
+        public virtual void SerializeAsV31WithoutReference(IOpenApiWriter writer) 
         {
             SerializeInternalWithoutReference(writer, OpenApiSpecVersion.OpenApi3_1);
         }
 
         /// <summary>
         /// Serialize to OpenAPI V3 example without using reference.
         /// </summary>
-        public void SerializeAsV3WithoutReference(IOpenApiWriter writer) 
+        public virtual void SerializeAsV3WithoutReference(IOpenApiWriter writer) 
         {
             SerializeInternalWithoutReference(writer, OpenApiSpecVersion.OpenApi3_0);
         }
 
-        private void SerializeInternalWithoutReference(IOpenApiWriter writer, OpenApiSpecVersion version)
+        internal void SerializeInternalWithoutReference(IOpenApiWriter writer, OpenApiSpecVersion version)
         {
             writer.WriteStartObject();
 

src/Microsoft.OpenApi/Models/OpenApiExtensibleDictionary.cs

@@ -6,7 +6,6 @@
 using System.Text.Json.Nodes;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Writers;
-using static Microsoft.OpenApi.Extensions.OpenApiSerializableExtensions;
 
 namespace Microsoft.OpenApi.Models
 {

src/Microsoft.OpenApi/Models/OpenApiExternalDocs.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;