Read example/summary from positional records (domaindrivendev#2546)

Add support for reading summary and example from default type constructor for C# 9 records. Resolves domaindrivendev#1920. --------- Co-authored-by: pixellos <codereinvented@gmail.com>
jcracknell · Apr 15, 2024 · 0fb4b06 · 0fb4b06
1 parent 0c4a175
commit 0fb4b06
Show file tree

Hide file tree

Showing 3 changed files with 74 additions and 10 deletions.
diff --git a/src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsSchemaFilter.cs b/src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsSchemaFilter.cs
@@ -39,21 +39,41 @@ private void ApplyMemberTags(OpenApiSchema schema, SchemaFilterContext context)
             var fieldOrPropertyMemberName = XmlCommentsNodeNameHelper.GetMemberNameForFieldOrProperty(context.MemberInfo);
             var fieldOrPropertyNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{fieldOrPropertyMemberName}']");
 
-            if (fieldOrPropertyNode == null) return;
+            var recordTypeName = XmlCommentsNodeNameHelper.GetMemberNameForType(context.MemberInfo.DeclaringType);
+            var recordDefaultConstructorProperty =
+                _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{recordTypeName}']/param[@name='{context.MemberInfo.Name}']");
 
-            var summaryNode = fieldOrPropertyNode.SelectSingleNode("summary");
-            if (summaryNode != null)
-                schema.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
+            if (recordDefaultConstructorProperty != null)
+            {
+                var summaryNode = recordDefaultConstructorProperty.Value;
+                if (summaryNode != null)
+                    schema.Description = XmlCommentsTextHelper.Humanize(summaryNode);
+
+                var example = recordDefaultConstructorProperty.GetAttribute("example", string.Empty);
+                TrySetExample(schema, context, example);
+            }
 
-            var exampleNode = fieldOrPropertyNode.SelectSingleNode("example");
-            if (exampleNode != null)
+            if (fieldOrPropertyNode != null)
             {
-                var exampleAsJson = (schema.ResolveType(context.SchemaRepository) == "string") && !exampleNode.Value.Equals("null")
-                    ? $"\"{exampleNode.ToString()}\""
-                    : exampleNode.ToString();
+                var summaryNode = fieldOrPropertyNode.SelectSingleNode("summary");
+                if (summaryNode != null)
+                    schema.Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
 
-                schema.Example = OpenApiAnyFactory.CreateFromJson(exampleAsJson);
+                var exampleNode = fieldOrPropertyNode.SelectSingleNode("example");
+                TrySetExample(schema, context, exampleNode?.Value);
             }
         }
+
+        private static void TrySetExample(OpenApiSchema schema, SchemaFilterContext context, string example)
+        {
+            if (example == null)
+                return;
+
+            var exampleAsJson = (schema.ResolveType(context.SchemaRepository) == "string") && !example.Equals("null")
+                ? $"\"{example}\""
+                : example;
+
+            schema.Example = OpenApiAnyFactory.CreateFromJson(exampleAsJson);
+        }
     }
 }
diff --git a/test/Swashbuckle.AspNetCore.SwaggerGen.Test/Fixtures/XmlAnnotatedRecord.cs b/test/Swashbuckle.AspNetCore.SwaggerGen.Test/Fixtures/XmlAnnotatedRecord.cs
@@ -0,0 +1,33 @@
+using System;
+using Swashbuckle.AspNetCore.TestSupport;
+
+namespace Swashbuckle.AspNetCore.SwaggerGen.Test
+{
+    /// <summary>
+    /// Summary for XmlAnnotatedType
+    /// </summary>
+    /// <param name="BoolProperty" example="true">Summary for BoolProperty</param>
+    /// <param name="IntProperty" example="10">Summary for IntProperty</param>
+    /// <param name="LongProperty" example="4294967295">Summary for LongProperty</param>
+    /// <param name="FloatProperty" example="1.2">Summary for FloatProperty</param>
+    /// <param name="DoubleProperty" example="1.25">Summary for DoubleProperty</param>
+    /// <param name="EnumProperty" example="2">Summary for EnumProperty</param>
+    /// <param name="GuidProperty" example="d3966535-2637-48fa-b911-e3c27405ee09">Summary for GuidProperty</param>
+    /// <param name="StringPropertyWithNullExample" example="null">Summary for Nullable StringPropertyWithNullExample</param>
+    /// <param name="StringProperty" example="Example for StringProperty">Summary for StringProperty</param>
+    /// <param name="StringPropertyWithUri" example="https://test.com/a?b=1&amp;c=2">Summary for StringPropertyWithUri</param>
+    /// <param name="ObjectProperty" example="{&quot;prop1&quot;: 1, &quot;prop2&quot;: &quot;foobar&quot;}">Summary for ObjectProperty</param>
+    public record XmlAnnotatedRecord(
+        bool BoolProperty,
+        int IntProperty,
+        long LongProperty,
+        float FloatProperty,
+        double DoubleProperty,
+        IntEnum EnumProperty,
+        Guid GuidProperty,
+        string StringPropertyWithNullExample,
+        string StringProperty,
+        string StringPropertyWithUri,
+        object ObjectProperty
+        );
+}
diff --git a/test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsSchemaFilterTests.cs b/test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsSchemaFilterTests.cs
@@ -68,6 +68,17 @@ public void Apply_SetsDescription_FromPropertySummaryTag(
         [InlineData(typeof(XmlAnnotatedType), nameof(XmlAnnotatedType.ObjectProperty), "object", "{\n  \"prop1\": 1,\n  \"prop2\": \"foobar\"\n}")]
         [InlineData(typeof(XmlAnnotatedType), nameof(XmlAnnotatedType.StringPropertyWithNullExample), "string", "null")]
         [InlineData(typeof(XmlAnnotatedType), nameof(XmlAnnotatedType.StringPropertyWithUri), "string", "\"https://test.com/a?b=1&c=2\"")]
+        [InlineData(typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.BoolProperty), "boolean", "true")]
+        [InlineData(typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.IntProperty), "integer", "10")]
+        [InlineData(typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.LongProperty), "integer", "4294967295")]
+        [InlineData(typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.FloatProperty), "number", "1.2")]
+        [InlineData(typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.DoubleProperty), "number", "1.25")]
+        [InlineData(typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.EnumProperty), "integer", "2")]
+        [InlineData(typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.GuidProperty), "string", "\"d3966535-2637-48fa-b911-e3c27405ee09\"")]
+        [InlineData(typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.StringProperty), "string", "\"Example for StringProperty\"")]
+        [InlineData(typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.ObjectProperty), "object", "{\n  \"prop1\": 1,\n  \"prop2\": \"foobar\"\n}")]
+        [InlineData(typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.StringPropertyWithNullExample), "string", "null")]
+        [InlineData(typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.StringPropertyWithUri), "string", "\"https://test.com/a?b=1&c=2\"")]
         [UseInvariantCulture]
         public void Apply_SetsExample_FromPropertyExampleTag(
             Type declaringType,