Merge pull request #1769 from captainsafia/property-bag-support

MaggieKimani1 · web-flow · commit 7876018a15fb · 2024-08-05T22:28:27.000+03:00
Add support for unserializable annotations on OpenAPI document
diff --git a/src/Microsoft.OpenApi/Interfaces/IOpenApiAnnotatable.cs b/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; }
+    }
+}
diff --git a/src/Microsoft.OpenApi/Models/OpenApiDocument.cs b/src/Microsoft.OpenApi/Models/OpenApiDocument.cs
@@ -17,7 +17,7 @@ namespace Microsoft.OpenApi.Models
     /// <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 @@ public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible
         /// </summary>
         public string HashCode => GenerateHashValue(this);
 
+        /// <inheritdoc />
+        public IDictionary<string, object> Annotations { get; set; }
+
         /// <summary>
         /// Parameter-less constructor
         /// </summary>
@@ -89,6 +92,7 @@ public OpenApiDocument(OpenApiDocument document)
             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>
diff --git a/src/Microsoft.OpenApi/Models/OpenApiOperation.cs b/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>
diff --git a/src/Microsoft.OpenApi/Models/OpenApiSchema.cs b/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>
diff --git a/test/Microsoft.OpenApi.Tests/Models/OpenApiDocumentTests.cs b/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"]);
+        }
     }
 }
diff --git a/test/Microsoft.OpenApi.Tests/Models/OpenApiOperationTests.cs b/test/Microsoft.OpenApi.Tests/Models/OpenApiOperationTests.cs
@@ -87,7 +87,8 @@ public class OpenApiOperationTests
                     Url = "http://server.com",
                     Description = "serverDescription"
                 }
-            }
+            },
+            Annotations = new Dictionary<string, object> { { "key1", "value1" }, { "key2", 2 } },
         };
 
         private static readonly OpenApiOperation _advancedOperationWithTagsAndSecurity = new()
@@ -864,5 +865,26 @@ public void EnsureOpenApiOperationCopyConstructor_SerializationResultsInSame()
                 actual.Should().Be(expected);
             }
         }
+
+        [Fact]
+        public void OpenApiOperationCopyConstructorWithAnnotationsSucceeds()
+        {
+            var baseOperation = new OpenApiOperation
+            {
+                Annotations = new Dictionary<string, object>
+                {
+                    ["key1"] = "value1",
+                    ["key2"] = 2
+                }
+            };
+
+            var actualOperation = new OpenApiOperation(baseOperation);
+
+            Assert.Equal(baseOperation.Annotations["key1"], actualOperation.Annotations["key1"]);
+
+            baseOperation.Annotations["key1"] = "value2";
+
+            Assert.NotEqual(baseOperation.Annotations["key1"], actualOperation.Annotations["key1"]);
+        }
     }
 }
diff --git a/test/Microsoft.OpenApi.Tests/Models/OpenApiSchemaTests.cs b/test/Microsoft.OpenApi.Tests/Models/OpenApiSchemaTests.cs
@@ -36,7 +36,8 @@ public class OpenApiSchemaTests
             ExternalDocs = new()
             {
                 Url = new("http://example.com/externalDocs")
-            }
+            },
+            Annotations = new Dictionary<string, object> { { "key1", "value1" }, { "key2", 2 } }
         };
 
         public static readonly OpenApiSchema AdvancedSchemaObject = new()
@@ -483,6 +484,27 @@ public void OpenApiSchemaCopyConstructorSucceeds()
             Assert.True(actualSchema.Nullable);
         }
 
+        [Fact]
+        public void OpenApiSchemaCopyConstructorWithAnnotationsSucceeds()
+        {
+            var baseSchema = new OpenApiSchema
+            {
+                Annotations = new Dictionary<string, object>
+                {
+                    ["key1"] = "value1",
+                    ["key2"] = 2
+                }
+            };
+
+            var actualSchema = new OpenApiSchema(baseSchema);
+
+            Assert.Equal(baseSchema.Annotations["key1"], actualSchema.Annotations["key1"]);
+
+            baseSchema.Annotations["key1"] = "value2";
+
+            Assert.NotEqual(baseSchema.Annotations["key1"], actualSchema.Annotations["key1"]);
+        }
+
         public static TheoryData<IOpenApiAny> SchemaExamples()
         {
             return new()
diff --git a/test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt b/test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt
@@ -302,6 +302,10 @@ namespace Microsoft.OpenApi.Interfaces
     {
         T GetEffective(Microsoft.OpenApi.Models.OpenApiDocument document);
     }
+    public interface IOpenApiAnnotatable
+    {
+        System.Collections.Generic.IDictionary<string, object> Annotations { get; set; }
+    }
     public interface IOpenApiElement { }
     public interface IOpenApiExtensible : Microsoft.OpenApi.Interfaces.IOpenApiElement
     {
@@ -592,10 +596,11 @@ namespace Microsoft.OpenApi.Models
         public void SerializeAsV2(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
         public void SerializeAsV3(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
     }
-    public class OpenApiDocument : Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiSerializable
+    public class OpenApiDocument : Microsoft.OpenApi.Interfaces.IOpenApiAnnotatable, Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiSerializable
     {
         public OpenApiDocument() { }
         public OpenApiDocument(Microsoft.OpenApi.Models.OpenApiDocument document) { }
+        public System.Collections.Generic.IDictionary<string, object> Annotations { get; set; }
         public Microsoft.OpenApi.Models.OpenApiComponents Components { get; set; }
         public System.Collections.Generic.IDictionary<string, Microsoft.OpenApi.Interfaces.IOpenApiExtension> Extensions { get; set; }
         public Microsoft.OpenApi.Models.OpenApiExternalDocs ExternalDocs { get; set; }
@@ -774,11 +779,12 @@ namespace Microsoft.OpenApi.Models
         public void SerializeAsV2(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
         public void SerializeAsV3(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
     }
-    public class OpenApiOperation : Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiSerializable
+    public class OpenApiOperation : Microsoft.OpenApi.Interfaces.IOpenApiAnnotatable, Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiSerializable
     {
         public const bool DeprecatedDefault = false;
         public OpenApiOperation() { }
         public OpenApiOperation(Microsoft.OpenApi.Models.OpenApiOperation operation) { }
+        public System.Collections.Generic.IDictionary<string, object> Annotations { get; set; }
         public System.Collections.Generic.IDictionary<string, Microsoft.OpenApi.Models.OpenApiCallback> Callbacks { get; set; }
         public bool Deprecated { get; set; }
         public string Description { get; set; }
@@ -900,13 +906,14 @@ namespace Microsoft.OpenApi.Models
         public OpenApiResponses() { }
         public OpenApiResponses(Microsoft.OpenApi.Models.OpenApiResponses openApiResponses) { }
     }
-    public class OpenApiSchema : Microsoft.OpenApi.Interfaces.IEffective<Microsoft.OpenApi.Models.OpenApiSchema>, Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiReferenceable, Microsoft.OpenApi.Interfaces.IOpenApiSerializable
+    public class OpenApiSchema : Microsoft.OpenApi.Interfaces.IEffective<Microsoft.OpenApi.Models.OpenApiSchema>, Microsoft.OpenApi.Interfaces.IOpenApiAnnotatable, Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiReferenceable, Microsoft.OpenApi.Interfaces.IOpenApiSerializable
     {
         public OpenApiSchema() { }
         public OpenApiSchema(Microsoft.OpenApi.Models.OpenApiSchema schema) { }
         public Microsoft.OpenApi.Models.OpenApiSchema AdditionalProperties { get; set; }
         public bool AdditionalPropertiesAllowed { get; set; }
         public System.Collections.Generic.IList<Microsoft.OpenApi.Models.OpenApiSchema> AllOf { get; set; }
+        public System.Collections.Generic.IDictionary<string, object> Annotations { get; set; }
         public System.Collections.Generic.IList<Microsoft.OpenApi.Models.OpenApiSchema> AnyOf { get; set; }
         public Microsoft.OpenApi.Any.IOpenApiAny Default { get; set; }
         public bool Deprecated { get; set; }

Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,8 @@ public class OpenApiDocumentTests`
`29`	`29`	`{`
`30`	`30`	`Type = ReferenceType.Schema,`
`31`	`31`	`Id = "schema2"`
`32`		`- }`
	`32`	`+ },`
	`33`	`+ Annotations = new Dictionary<string, object> { { "x-foo", "bar" } }`
`33`	`34`	`},`
`34`	`35`	`["schema2"] = new()`
`35`	`36`	`{`
`@@ -38,7 +39,8 @@ public class OpenApiDocumentTests`
`38`	`39`	`{`
`39`	`40`	`["property1"] = new()`
`40`	`41`	`{`
`41`		`- Type = "string"`
	`42`	`+ Type = "string",`
	`43`	`+ Annotations = new Dictionary<string, object> { { "key1", "value" } }`
`42`	`44`	`}`
`43`	`45`	`}`
`44`	`46`	`},`
`@@ -56,9 +58,11 @@ public class OpenApiDocumentTests`
`56`	`58`	`{`
`57`	`59`	`["property1"] = new()`
`58`	`60`	`{`
`59`		`- Type = "string"`
	`61`	`+ Type = "string",`
	`62`	`+ Annotations = new Dictionary<string, object> { { "key1", "value" } }`
`60`	`63`	`}`
`61`	`64`	`},`
	`65`	`+ Annotations = new Dictionary<string, object> { { "key1", "value" } },`
`62`	`66`	`Reference = new()`
`63`	`67`	`{`
`64`	`68`	`Type = ReferenceType.Schema,`
`@@ -100,6 +104,7 @@ public class OpenApiDocumentTests`
`100`	`104`	`{`
`101`	`105`	`Version = "1.0.0"`
`102`	`106`	`},`
	`107`	`+ Annotations = new Dictionary<string, object> { { "key1", "value" } },`
`103`	`108`	`Components = TopLevelReferencingComponents`
`104`	`109`	`};`
`105`	`110`
`@@ -109,6 +114,7 @@ public class OpenApiDocumentTests`
`109`	`114`	`{`
`110`	`115`	`Version = "1.0.0"`
`111`	`116`	`},`
	`117`	`+ Annotations = new Dictionary<string, object> { { "key1", "value" } },`
`112`	`118`	`Components = TopLevelSelfReferencingComponentsWithOtherProperties`
`113`	`119`	`};`
`114`	`120`
`@@ -118,6 +124,7 @@ public class OpenApiDocumentTests`
`118`	`124`	`{`
`119`	`125`	`Version = "1.0.0"`
`120`	`126`	`},`
	`127`	`+ Annotations = new Dictionary<string, object> { { "key1", "value" } },`
`121`	`128`	`Components = TopLevelSelfReferencingComponents`
`122`	`129`	`};`
`123`	`130`
`@@ -509,6 +516,7 @@ public class OpenApiDocumentTests`
`509`	`516`	`}`
`510`	`517`	`}`
`511`	`518`	`},`
	`519`	`+ Annotations = new Dictionary<string, object> { { "key1", "value" } },`
`512`	`520`	`Components = AdvancedComponentsWithReference`
`513`	`521`	`};`
`514`	`522`
`@@ -884,6 +892,7 @@ public class OpenApiDocumentTests`
`884`	`892`	`}`
`885`	`893`	`}`
`886`	`894`	`},`
	`895`	`+ Annotations = new Dictionary<string, object> { { "key1", "value" } },`
`887`	`896`	`Components = AdvancedComponents`
`888`	`897`	`};`
`889`	`898`
`@@ -1272,6 +1281,7 @@ public class OpenApiDocumentTests`
`1272`	`1281`	`}`
`1273`	`1282`	`}`
`1274`	`1283`	`},`
	`1284`	`+ Annotations = new Dictionary<string, object> { { "key1", "value" } },`
`1275`	`1285`	`Components = AdvancedComponents`
`1276`	`1286`	`};`
`1277`	`1287`
`@@ -1827,5 +1837,26 @@ public void SerializeV2DocumentWithStyleAsNullDoesNotWriteOutStyleValue()`
`1827`	`1837`	`expected = expected.MakeLineBreaksEnvironmentNeutral();`
`1828`	`1838`	`actual.Should().Be(expected);`
`1829`	`1839`	`}`
	`1840`	`+`
	`1841`	`+ [Fact]`
	`1842`	`+ public void OpenApiDocumentCopyConstructorWithAnnotationsSucceeds()`
	`1843`	`+ {`
	`1844`	`+ var baseDocument = new OpenApiDocument`
	`1845`	`+ {`
	`1846`	`+ Annotations = new Dictionary<string, object>`
	`1847`	`+ {`
	`1848`	`+ ["key1"] = "value1",`
	`1849`	`+ ["key2"] = 2`
	`1850`	`+ }`
	`1851`	`+ };`
	`1852`	`+`
	`1853`	`+ var actualDocument = new OpenApiDocument(baseDocument);`
	`1854`	`+`
	`1855`	`+ Assert.Equal(baseDocument.Annotations["key1"], actualDocument.Annotations["key1"]);`
	`1856`	`+`
	`1857`	`+ baseDocument.Annotations["key1"] = "value2";`
	`1858`	`+`
	`1859`	`+ Assert.NotEqual(baseDocument.Annotations["key1"], actualDocument.Annotations["key1"]);`
	`1860`	`+ }`
`1830`	`1861`	`}`
`1831`	`1862`	`}`