Write full objects in components / Fix components missing issue when V2 document is parsed

src/Microsoft.OpenApi.Readers/V2/OpenApiDocumentDeserializer.cs

@@ -3,7 +3,6 @@
 //  Licensed under the MIT License (MIT). See LICENSE in the repo root for license information.
 // ------------------------------------------------------------
 
-using System;
 using System.Collections.Generic;
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Models;
@@ -19,7 +18,11 @@ internal static partial class OpenApiV2Deserializer
     {
         public static FixedFieldMap<OpenApiDocument> OpenApiFixedFields = new FixedFieldMap<OpenApiDocument>
         {
-            {"swagger", (o, n) => { } /* Version is valid field but we already parsed it */  },
+            {
+                "swagger", (o, n) =>
+                {
+                } /* Version is valid field but we already parsed it */
+            },
             {"info", (o, n) => o.Info = LoadInfo(n)},
             {"host", (o, n) => n.Context.SetTempStorage("host", n.GetScalarValue())},
             {"basePath", (o, n) => n.Context.SetTempStorage("basePath", n.GetScalarValue())},
@@ -40,34 +43,54 @@ internal static partial class OpenApiV2Deserializer
             {"paths", (o, n) => o.Paths = LoadPaths(n)},
             {
                 "definitions",
-                (o, n) => {
-                    o.Components = new OpenApiComponents();
-                    o.Components.Schemas = n.CreateMapWithReference(
-                    ReferenceType.Schema,
-                    "#/definitions/",
-                    LoadSchema);
+                (o, n) =>
+                {
+                    if (o.Components == null)
+                    {
+                        o.Components = new OpenApiComponents();
                     }
+
+                    o.Components.Schemas = n.CreateMapWithReference(
+                        ReferenceType.Schema,
+                        "#/definitions/",
+                        LoadSchema);
+                }
             },
             {
                 "parameters",
-                (o, n) => {
-                    o.Components = new OpenApiComponents();
-                    o.Components.Parameters = n.CreateMapWithReference(
-                    ReferenceType.Parameter,
-                    "#/parameters/",
-                    LoadParameter);
+                (o, n) =>
+                {
+                    if (o.Components == null)
+                    {
+                        o.Components = new OpenApiComponents();
                     }
+
+                    o.Components.Parameters = n.CreateMapWithReference(
+                        ReferenceType.Parameter,
+                        "#/parameters/",
+                        LoadParameter);
+                }
             },
             {
-                "responses", (o, n) => {
-                o.Components = new OpenApiComponents();
-                o.Components.Responses = n.CreateMap(LoadResponse);
+                "responses", (o, n) =>
+                {
+                    if (o.Components == null)
+                    {
+                        o.Components = new OpenApiComponents();
+                    }
+
+                    o.Components.Responses = n.CreateMap(LoadResponse);
                 }
             },
             {
-                "securityDefinitions", (o, n) => {
-                o.Components = new OpenApiComponents();
-                o.Components.SecuritySchemes = n.CreateMap(LoadSecurityScheme);
+                "securityDefinitions", (o, n) =>
+                {
+                    if (o.Components == null)
+                    {
+                        o.Components = new OpenApiComponents();
+                    }
+
+                    o.Components.SecuritySchemes = n.CreateMap(LoadSecurityScheme);
                 }
             },
             {"security", (o, n) => o.SecurityRequirements = n.CreateList(LoadSecurityRequirement)},

src/Microsoft.OpenApi/Interfaces/IOpenApiReferenceable.cs

@@ -4,17 +4,28 @@
 // ------------------------------------------------------------
 
 using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Writers;
 
 namespace Microsoft.OpenApi.Interfaces
 {
     /// <summary>
     /// Represents an Open API element is referenceable.
     /// </summary>
-    public interface IOpenApiReferenceable : IOpenApiElement
+    public interface IOpenApiReferenceable : IOpenApiSerializable
     {
         /// <summary>
         /// Reference object.
         /// </summary>
         OpenApiReference Reference { get; set; }
+
+        /// <summary>
+        /// Serialize to OpenAPI V3 document without using reference.
+        /// </summary>
+        void SerializeAsV3WithoutReference(IOpenApiWriter writer);
+
+        /// <summary>
+        /// Serialize to OpenAPI V2 document without using reference.
+        /// </summary>
+        void SerializeAsV2WithoutReference(IOpenApiWriter writer);
     }
 }

src/Microsoft.OpenApi/Models/OpenApiCallback.cs

@@ -70,22 +70,30 @@ public void SerializeAsV3(IOpenApiWriter writer)
             if (Reference != null)
             {
                 Reference.SerializeAsV3(writer);
+                return;
             }
-            else
-            {
-                writer.WriteStartObject();
+
+            SerializeAsV3WithoutReference(writer);
+        }
 
-                // path items
-                foreach (var item in PathItems)
-                {
-                    writer.WriteRequiredObject(item.Key.Expression, item.Value, (w, p) => p.SerializeAsV3(w));
-                }
+        /// <summary>
+        /// Serialize to OpenAPI V3 document without using reference.
+        /// </summary>
 
-                // extensions
-                writer.WriteExtensions(Extensions);
+        public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
+        {
+            writer.WriteStartObject();
 
-                writer.WriteEndObject();
+            // path items
+            foreach (var item in PathItems)
+            {
+                writer.WriteRequiredObject(item.Key.Expression, item.Value, (w, p) => p.SerializeAsV3(w));
             }
+
+            // extensions
+            writer.WriteExtensions(Extensions);
+
+            writer.WriteEndObject();
         }
 
         /// <summary>
@@ -95,5 +103,14 @@ public void SerializeAsV2(IOpenApiWriter writer)
         {
             // Callback object does not exist in V2.
         }
+
+        /// <summary>
+        /// Serialize to OpenAPI V2 document without using reference.
+        /// </summary>
+
+        public void SerializeAsV2WithoutReference(IOpenApiWriter writer)
+        {
+            // Callback object does not exist in V2.
+        }
     }
 }

src/Microsoft.OpenApi/Models/OpenApiComponents.cs

@@ -78,31 +78,31 @@ public void SerializeAsV3(IOpenApiWriter writer)
             writer.WriteStartObject();
 
             // schemas
-            writer.WriteOptionalMap(OpenApiConstants.Schemas, Schemas, (w, s) => s.SerializeAsV3(w));
+            writer.WriteOptionalMap(OpenApiConstants.Schemas, Schemas, (w, s) => s.SerializeAsV3WithoutReference(w));
 
             // responses
-            writer.WriteOptionalMap(OpenApiConstants.Responses, Responses, (w, r) => r.SerializeAsV3(w));
+            writer.WriteOptionalMap(OpenApiConstants.Responses, Responses, (w, r) => r.SerializeAsV3WithoutReference(w));
 
             // parameters
-            writer.WriteOptionalMap(OpenApiConstants.Parameters, Parameters, (w, p) => p.SerializeAsV3(w));
+            writer.WriteOptionalMap(OpenApiConstants.Parameters, Parameters, (w, p) => p.SerializeAsV3WithoutReference(w));
 
             // examples
-            writer.WriteOptionalMap(OpenApiConstants.Examples, Examples, (w, e) => e.SerializeAsV3(w));
+            writer.WriteOptionalMap(OpenApiConstants.Examples, Examples, (w, e) => e.SerializeAsV3WithoutReference(w));
 
             // requestBodies
-            writer.WriteOptionalMap(OpenApiConstants.RequestBodies, RequestBodies, (w, r) => r.SerializeAsV3(w));
+            writer.WriteOptionalMap(OpenApiConstants.RequestBodies, RequestBodies, (w, r) => r.SerializeAsV3WithoutReference(w));
 
             // headers
-            writer.WriteOptionalMap(OpenApiConstants.Headers, Headers, (w, h) => h.SerializeAsV3(w));
+            writer.WriteOptionalMap(OpenApiConstants.Headers, Headers, (w, h) => h.SerializeAsV3WithoutReference(w));
 
             // securitySchemes
-            writer.WriteOptionalMap(OpenApiConstants.SecuritySchemes, SecuritySchemes, (w, s) => s.SerializeAsV3(w));
+            writer.WriteOptionalMap(OpenApiConstants.SecuritySchemes, SecuritySchemes, (w, s) => s.SerializeAsV3WithoutReference(w));
 
             // links
-            writer.WriteOptionalMap(OpenApiConstants.Links, Links, (w, link) => link.SerializeAsV3(w));
+            writer.WriteOptionalMap(OpenApiConstants.Links, Links, (w, link) => link.SerializeAsV3WithoutReference(w));
 
             // callbacks
-            writer.WriteOptionalMap(OpenApiConstants.Callbacks, Callbacks, (w, c) => c.SerializeAsV3(w));
+            writer.WriteOptionalMap(OpenApiConstants.Callbacks, Callbacks, (w, c) => c.SerializeAsV3WithoutReference(w));
 
             // extensions
             writer.WriteExtensions(Extensions);

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -89,7 +89,7 @@ public void SerializeAsV3(IOpenApiWriter writer)
             writer.WriteOptionalCollection(OpenApiConstants.Security, SecurityRequirements, (w, s) => s.SerializeAsV3(w));
 
             // tags
-            writer.WriteOptionalCollection(OpenApiConstants.Tags, Tags, (w, t) => t.SerializeAsV3(w));
+            writer.WriteOptionalCollection(OpenApiConstants.Tags, Tags, (w, t) => t.SerializeAsV3WithoutReference(w));
 
             // external docs
             writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, e) => e.SerializeAsV3(w));
@@ -125,22 +125,22 @@ public void SerializeAsV2(IOpenApiWriter writer)
             writer.WriteRequiredObject(OpenApiConstants.Paths, Paths, (w, p) => p.SerializeAsV2(w));
 
             // definitions
-            writer.WriteOptionalMap(OpenApiConstants.Definitions, Components?.Schemas, (w, s) => s.SerializeAsV2(w));
+            writer.WriteOptionalMap(OpenApiConstants.Definitions, Components?.Schemas, (w, s) => s.SerializeAsV2WithoutReference(w));
 
             // parameters
-            writer.WriteOptionalMap(OpenApiConstants.Parameters, Components?.Parameters, (w, p) => p.SerializeAsV2(w));
+            writer.WriteOptionalMap(OpenApiConstants.Parameters, Components?.Parameters, (w, p) => p.SerializeAsV2WithoutReference(w));
 
             // responses
-            writer.WriteOptionalMap(OpenApiConstants.Responses, Components?.Responses, (w, r) => r.SerializeAsV2(w));
+            writer.WriteOptionalMap(OpenApiConstants.Responses, Components?.Responses, (w, r) => r.SerializeAsV2WithoutReference(w));
 
             // securityDefinitions
-            writer.WriteOptionalMap(OpenApiConstants.SecurityDefinitions, Components?.SecuritySchemes, (w, s) => s.SerializeAsV2(w));
+            writer.WriteOptionalMap(OpenApiConstants.SecurityDefinitions, Components?.SecuritySchemes, (w, s) => s.SerializeAsV2WithoutReference(w));
 
             // security
             writer.WriteOptionalCollection(OpenApiConstants.Security, SecurityRequirements, (w, s) => s.SerializeAsV2(w));
 
             // tags
-            writer.WriteOptionalCollection(OpenApiConstants.Tags, Tags, (w, t) => t.SerializeAsV2(w));
+            writer.WriteOptionalCollection(OpenApiConstants.Tags, Tags, (w, t) => t.SerializeAsV2WithoutReference(w));
 
             // externalDocs
             writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, e) => e.SerializeAsV2(w));

src/Microsoft.OpenApi/Models/OpenApiExample.cs

@@ -27,16 +27,16 @@ public class OpenApiExample : IOpenApiSerializable, IOpenApiReferenceable, IOpen
         public 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 
+        /// 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 IOpenApiAny 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. 
+        /// 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; }
@@ -49,10 +49,7 @@ public class OpenApiExample : IOpenApiSerializable, IOpenApiReferenceable, IOpen
         /// <summary>
         /// Reference object.
         /// </summary>
-        public OpenApiReference Reference
-        {
-            get; set;
-        }
+        public OpenApiReference Reference { get; set; }
 
         /// <summary>
         /// Serialize <see cref="OpenApiExample"/> to Open Api v3.0
@@ -67,28 +64,35 @@ public void SerializeAsV3(IOpenApiWriter writer)
             if (Reference != null)
             {
                 Reference.SerializeAsV3(writer);
+                return;
             }
-            else
-            {
-                writer.WriteStartObject();
 
-                // summary
-                writer.WriteProperty(OpenApiConstants.Summary, Summary);
+            SerializeAsV3WithoutReference(writer);
+        }
 
-                // description
-                writer.WriteProperty(OpenApiConstants.Description, Description);
+        /// <summary>
+        /// Serialize to OpenAPI V3 document without using reference.
+        /// </summary>
+        public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
+        {
+            writer.WriteStartObject();
 
-                // value
-                writer.WriteOptionalObject(OpenApiConstants.Value, Value, (w, v) => w.WriteAny(v));
+            // summary
+            writer.WriteProperty(OpenApiConstants.Summary, Summary);
 
-                // externalValue
-                writer.WriteProperty(OpenApiConstants.ExternalValue, ExternalValue);
+            // description
+            writer.WriteProperty(OpenApiConstants.Description, Description);
 
-                // extensions
-                writer.WriteExtensions(Extensions);
+            // value
+            writer.WriteOptionalObject(OpenApiConstants.Value, Value, (w, v) => w.WriteAny(v));
 
-                writer.WriteEndObject();
-            }
+            // externalValue
+            writer.WriteProperty(OpenApiConstants.ExternalValue, ExternalValue);
+
+            // extensions
+            writer.WriteExtensions(Extensions);
+
+            writer.WriteEndObject();
         }
 
         /// <summary>
@@ -100,5 +104,15 @@ public void SerializeAsV2(IOpenApiWriter writer)
             // V2 Example object requires knowledge of media type and exists only
             // in Response object, so it will be serialized as a part of the Response object.
         }
+
+        /// <summary>
+        /// Serialize to OpenAPI V2 document without using reference.
+        /// </summary>
+        public void SerializeAsV2WithoutReference(IOpenApiWriter writer)
+        {
+            // Example object of this form does not exist in V2.
+            // V2 Example object requires knowledge of media type and exists only
+            // in Response object, so it will be serialized as a part of the Response object.
+        }
     }
-}
+}