Deploy libs

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

@@ -3,7 +3,7 @@
         <TargetFramework>netstandard2.0</TargetFramework>
         <LangVersion>latest</LangVersion>
         <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
-        <Version>1.6.16</Version>
+        <Version>1.6.17</Version>
         <Description>OpenAPI.NET Readers for JSON and YAML documents</Description>
         <SignAssembly>true</SignAssembly>
         <!-- https://github.com/dotnet/sourcelink/blob/main/docs/README.md#embeduntrackedsources -->

src/Microsoft.OpenApi/Interfaces/IOpenApiAnnotatable.cs

@@ -0,0 +1,19 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+using System.Collections.Generic;
+
+namespace Microsoft.OpenApi.Interfaces
+{
+    /// <summary>
+    /// Represents an Open API element that can be annotated with
+    /// non-serializable properties in a property bag. 
+    /// </summary>
+    public interface IOpenApiAnnotatable
+    {
+        /// <summary>
+        /// A collection of properties associated with the current OpenAPI element.
+        /// </summary>
+        IDictionary<string, object> Annotations { get; set; }
+    }
+}

src/Microsoft.OpenApi/Microsoft.OpenApi.csproj

@@ -3,7 +3,7 @@
         <TargetFramework>netstandard2.0</TargetFramework>
         <LangVersion>Latest</LangVersion>
         <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
-        <Version>1.6.16</Version>
+        <Version>1.6.17</Version>
         <Description>.NET models with JSON and YAML writers for OpenAPI specification</Description>
         <SignAssembly>true</SignAssembly>
         <!-- https://github.com/dotnet/sourcelink/blob/main/docs/README.md#embeduntrackedsources -->

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -17,7 +17,7 @@
     /// <summary>
     /// Describes an OpenAPI object (OpenAPI document). See: https://swagger.io/specification
     /// </summary>
-    public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible
+    public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible, IOpenApiAnnotatable
     {
         /// <summary>
         /// Related workspace containing OpenApiDocuments that are referenced in this document
@@ -70,6 +70,9 @@
         /// </summary>
         public string HashCode => GenerateHashValue(this);
 
+        /// <inheritdoc />
+        public IDictionary<string, object> Annotations { get; set; }
+
         /// <summary>
         /// Parameter-less constructor
         /// </summary>
@@ -89,6 +92,7 @@
             Tags = document?.Tags != null ? new List<OpenApiTag>(document.Tags) : null;
             ExternalDocs = document?.ExternalDocs != null ? new(document?.ExternalDocs) : null;
             Extensions = document?.Extensions != null ? new Dictionary<string, IOpenApiExtension>(document.Extensions) : null;
+            Annotations = document?.Annotations != null ? new Dictionary<string, object>(document.Annotations) : null;
         }
 
         /// <summary>
@@ -437,7 +441,7 @@
                 return null;
             }
 
             // Todo: Verify if we need to check to see if this external reference is actually targeted at this document.
             if (useExternal)
             {
                 if (this.Workspace == null)

src/Microsoft.OpenApi/Models/OpenApiMediaType.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT license.
 
 using System.Collections.Generic;
+using System.Linq;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Writers;
@@ -76,7 +77,7 @@ public void SerializeAsV3(IOpenApiWriter writer)
             writer.WriteOptionalObject(OpenApiConstants.Example, Example, (w, e) => w.WriteAny(e));
 
             // examples
-            writer.WriteOptionalMap(OpenApiConstants.Examples, Examples, (w, e) => e.SerializeAsV3(w));
+            SerializeExamples(writer, Examples);
 
             // encoding
             writer.WriteOptionalMap(OpenApiConstants.Encoding, Encoding, (w, e) => e.SerializeAsV3(w));
@@ -94,5 +95,33 @@ public void SerializeAsV2(IOpenApiWriter writer)
         {
             // Media type does not exist in V2.
         }
+
+        private static void SerializeExamples(IOpenApiWriter writer, IDictionary<string, OpenApiExample> examples)
+        {
+            /* Special case for writing out empty arrays as valid response examples
+            * Check if there is any example with an empty array as its value and set the flag `hasEmptyArray` to true
+            * */
+            var hasEmptyArray = examples.Values.Any( static example =>
+                example.Value is OpenApiArray arr && arr.Count == 0
+            );
+
+            if (hasEmptyArray)
+            {
+                writer.WritePropertyName(OpenApiConstants.Examples);
+                writer.WriteStartObject();
+                foreach (var kvp in examples.Where(static kvp => kvp.Value.Value is OpenApiArray arr && arr.Count == 0))
+                {
+                    writer.WritePropertyName(kvp.Key);
+                    writer.WriteStartObject();
+                    writer.WriteRequiredObject(OpenApiConstants.Value, kvp.Value.Value, (w, v) => w.WriteAny(v));
+                    writer.WriteEndObject();
+                }
+                writer.WriteEndObject();
+            }
+            else
+            {
+                writer.WriteOptionalMap(OpenApiConstants.Examples, examples, (w, e) => e.SerializeAsV3(w));
+            }
+        }
     }
 }

src/Microsoft.OpenApi/Models/OpenApiOperation.cs

@@ -12,7 +12,7 @@ namespace Microsoft.OpenApi.Models
     /// <summary>
     /// Operation Object.
     /// </summary>
-    public class OpenApiOperation : IOpenApiSerializable, IOpenApiExtensible
+    public class OpenApiOperation : IOpenApiSerializable, IOpenApiExtensible, IOpenApiAnnotatable
     {
         /// <summary>
         /// Default value for <see cref="Deprecated"/>.
@@ -105,6 +105,9 @@ public class OpenApiOperation : IOpenApiSerializable, IOpenApiExtensible
         /// </summary>
         public IDictionary<string, IOpenApiExtension> Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
 
+        /// <inheritdoc />
+        public IDictionary<string, object> Annotations { get; set; }
+
         /// <summary>
         /// Parameterless constructor
         /// </summary>
@@ -128,6 +131,7 @@ public OpenApiOperation(OpenApiOperation operation)
             Security = operation?.Security != null ? new List<OpenApiSecurityRequirement>(operation.Security) : null;
             Servers = operation?.Servers != null ? new List<OpenApiServer>(operation.Servers) : null;
             Extensions = operation?.Extensions != null ? new Dictionary<string, IOpenApiExtension>(operation.Extensions) : null;
+            Annotations = operation?.Annotations != null ? new Dictionary<string, object>(operation.Annotations) : null;
         }
 
         /// <summary>

src/Microsoft.OpenApi/Models/OpenApiReference.cs

@@ -148,13 +148,6 @@ public void SerializeAsV3(IOpenApiWriter writer)
                 return;
             }
 
-            if (Type == ReferenceType.SecurityScheme)
-            {
-                // Write the string as property name
-                writer.WritePropertyName(ReferenceV3);
-                return;
-            }
-
             writer.WriteStartObject();
 
             // $ref

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -12,7 +12,7 @@ namespace Microsoft.OpenApi.Models
     /// <summary>
     /// Schema Object.
     /// </summary>
-    public class OpenApiSchema : IOpenApiReferenceable, IEffective<OpenApiSchema>, IOpenApiExtensible
+    public class OpenApiSchema : IOpenApiReferenceable, IEffective<OpenApiSchema>, IOpenApiExtensible, IOpenApiAnnotatable
     {
         /// <summary>
         /// Follow JSON Schema definition. Short text providing information about the data.
@@ -241,6 +241,9 @@ public class OpenApiSchema : IOpenApiReferenceable, IEffective<OpenApiSchema>, I
         /// </summary>
         public OpenApiReference Reference { get; set; }
 
+        /// <inheritdoc />
+        public IDictionary<string, object> Annotations { get; set; }
+
         /// <summary>
         /// Parameterless constructor
         /// </summary>
@@ -290,6 +293,7 @@ public OpenApiSchema(OpenApiSchema schema)
             Extensions = schema?.Extensions != null ? new Dictionary<string, IOpenApiExtension>(schema.Extensions) : null;
             UnresolvedReference = schema?.UnresolvedReference ?? UnresolvedReference;
             Reference = schema?.Reference != null ? new(schema?.Reference) : null;
+            Annotations = schema?.Annotations != null ? new Dictionary<string, object>(schema?.Annotations) : null;
         }
 
         /// <summary>

src/Microsoft.OpenApi/Models/OpenApiSecurityRequirement.cs

@@ -50,7 +50,7 @@
                     continue;
                 }
 
-                securityScheme.SerializeAsV3(writer);
+                writer.WritePropertyName(securityScheme.Reference.ReferenceV3);
 
                 writer.WriteStartArray();
 
@@ -106,7 +106,7 @@
         /// Comparer for OpenApiSecurityScheme that only considers the Id in the Reference
         /// (i.e. the string that will actually be displayed in the written document)
         /// </summary>
         private class OpenApiSecuritySchemeReferenceEqualityComparer : IEqualityComparer<OpenApiSecurityScheme>
         {
             /// <summary>
             /// Determines whether the specified objects are equal.

test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiMediaTypeTests.cs

@@ -4,9 +4,11 @@
 using System.IO;
 using FluentAssertions;
 using Microsoft.OpenApi.Any;
+using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.ParseNodes;
 using Microsoft.OpenApi.Readers.V3;
+using Microsoft.OpenApi.Tests;
 using Xunit;
 
 namespace Microsoft.OpenApi.Readers.Tests.V3Tests
@@ -77,5 +79,43 @@ public void ParseMediaTypeWithExamplesShouldSucceed()
                     }
                 });
         }
+
+        [Fact]
+        public void ParseMediaTypeWithEmptyArrayInExamplesWorks()
+        {
+            // Arrange
+            var expected = @"{
+  ""schema"": {
+    ""type"": ""array"",
+    ""items"": {
+      ""type"": ""object"",
+      ""properties"": {
+        ""id"": {
+          ""type"": ""string""
+        }
+      }
+    }
+  },
+  ""examples"": {
+    ""Success response - no results"": {
+      ""value"": [ ]
+    }
+  }
+}
+";
+            MapNode node;
+            using (var stream = Resources.GetStream(Path.Combine(SampleFolderPath, "examplesWithEmptyArray.json")))
+            {
+                node = TestHelper.CreateYamlMapNode(stream);
+            }
+
+            // Act
+            var mediaType = OpenApiV3Deserializer.LoadMediaType(node);
+            var serialized = mediaType.SerializeAsJson(OpenApiSpecVersion.OpenApi3_0);
+
+            // Assert
+            serialized.MakeLineBreaksEnvironmentNeutral()
+                .Should().BeEquivalentTo(expected.MakeLineBreaksEnvironmentNeutral());
+        }
     }
 }

test/Microsoft.OpenApi.Readers.Tests/V3Tests/Samples/OpenApiMediaType/examplesWithEmptyArray.json

@@ -0,0 +1,18 @@
+{
+  "schema": {
+    "type": "array",
+    "items": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "examples": {
+    "Success response - no results": {
+      "value": []
+    }
+  }
+}

test/Microsoft.OpenApi.Tests/Microsoft.OpenApi.Tests.csproj

@@ -15,7 +15,7 @@
     <PackageReference Include="Moq" Version="4.20.70" />
     <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
     <PackageReference Include="SharpYaml" Version="2.1.1" />
-    <PackageReference Include="Verify.Xunit" Version="26.1.2" />
+    <PackageReference Include="Verify.Xunit" Version="26.1.6" />
     <PackageReference Include="xunit" Version="2.9.0" />
     <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2" PrivateAssets="all" />
     <PackageReference Include="Microsoft.CSharp" Version="4.7.0" />

test/Microsoft.OpenApi.Tests/Models/OpenApiDocumentTests.cs

@@ -29,7 +29,8 @@ public class OpenApiDocumentTests
                     {
                         Type = ReferenceType.Schema,
                         Id = "schema2"
-                    }
+                    },
+                    Annotations = new Dictionary<string, object> { { "x-foo", "bar" } }
                 },
                 ["schema2"] = new()
                 {
@@ -38,7 +39,8 @@ public class OpenApiDocumentTests
                     {
                         ["property1"] = new()
                         {
-                            Type = "string"
+                            Type = "string",
+                            Annotations = new Dictionary<string, object> { { "key1", "value" } }
                         }
                     }
                 },
@@ -56,9 +58,11 @@ public class OpenApiDocumentTests
                     {
                         ["property1"] = new()
                         {
-                            Type = "string"
+                            Type = "string",
+                            Annotations = new Dictionary<string, object> { { "key1", "value" } }
                         }
                     },
+                    Annotations = new Dictionary<string, object> { { "key1", "value" } },
                     Reference = new()
                     {
                         Type = ReferenceType.Schema,
@@ -100,6 +104,7 @@ public class OpenApiDocumentTests
             {
                 Version = "1.0.0"
             },
+            Annotations = new Dictionary<string, object> { { "key1", "value" } },
             Components = TopLevelReferencingComponents
         };
 
@@ -109,6 +114,7 @@ public class OpenApiDocumentTests
             {
                 Version = "1.0.0"
             },
+            Annotations = new Dictionary<string, object> { { "key1", "value" } },
             Components = TopLevelSelfReferencingComponentsWithOtherProperties
         };
 
@@ -118,6 +124,7 @@ public class OpenApiDocumentTests
             {
                 Version = "1.0.0"
             },
+            Annotations = new Dictionary<string, object> { { "key1", "value" } },
             Components = TopLevelSelfReferencingComponents
         };
 
@@ -509,6 +516,7 @@ public class OpenApiDocumentTests
                     }
                 }
             },
+            Annotations = new Dictionary<string, object> { { "key1", "value" } },
             Components = AdvancedComponentsWithReference
         };
 
@@ -884,6 +892,7 @@ public class OpenApiDocumentTests
                     }
                 }
             },
+            Annotations = new Dictionary<string, object> { { "key1", "value" } },
             Components = AdvancedComponents
         };
 
@@ -1272,6 +1281,7 @@ public class OpenApiDocumentTests
                     }
                 }
             },
+            Annotations = new Dictionary<string, object> { { "key1", "value" } },
             Components = AdvancedComponents
         };
 
@@ -1827,5 +1837,26 @@ public void SerializeV2DocumentWithStyleAsNullDoesNotWriteOutStyleValue()
             expected = expected.MakeLineBreaksEnvironmentNeutral();
             actual.Should().Be(expected);
         }
+
+        [Fact]
+        public void OpenApiDocumentCopyConstructorWithAnnotationsSucceeds()
+        {
+            var baseDocument = new OpenApiDocument
+            {
+                Annotations = new Dictionary<string, object>
+                {
+                    ["key1"] = "value1",
+                    ["key2"] = 2
+                }
+            };
+
+            var actualDocument = new OpenApiDocument(baseDocument);
+
+            Assert.Equal(baseDocument.Annotations["key1"], actualDocument.Annotations["key1"]);
+
+            baseDocument.Annotations["key1"] = "value2";
+
+            Assert.NotEqual(baseDocument.Annotations["key1"], actualDocument.Annotations["key1"]);
+        }
     }
 }