Implemented inheritdoc support for XML parser domaindrivendev/Swashbu…

…ckle.AspNetCore#2687 domaindrivendev/Swashbuckle.AspNetCore#2597 for Havunen/DotSwashbuckle#1
Havunen · Feb 12, 2024 · 8c301f3 · 8c301f3
1 parent 7078ab7
commit 8c301f3
Show file tree

Hide file tree

Showing 7 changed files with 206 additions and 6 deletions.
diff --git a/src/DotSwashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs b/src/DotSwashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs
@@ -487,6 +487,7 @@ private static string ReadInnerValueAsString(XmlReader xmlReader, string endBloc
                 CheckCharacters = false,
                 IgnoreWhitespace = true
             });
+            var membersWithInheritDoc = new List<(string, XmlCommentDescriptor)>();
             var xmlMembers = new Dictionary<string, XmlCommentDescriptor>(StringComparer.Ordinal);
 
             xmlReader.MoveToContent();
@@ -549,6 +550,11 @@ private static string ReadInnerValueAsString(XmlReader xmlReader, string endBloc
                                         }
                                     );
                                     break;
+                                case "inheritdoc":
+                                    xmlComment.InheritcDoc = xmlReader.GetAttribute("cref");
+                                    membersWithInheritDoc.Add((memberName, xmlComment));
+                                    xmlReader.Read();
+                                    break;
                                 default:
                                     xmlReader.Read();
                                     break;
@@ -568,7 +574,47 @@ private static string ReadInnerValueAsString(XmlReader xmlReader, string endBloc
                 }
             }
 
+            foreach (var (key, xmlComment) in membersWithInheritDoc)
+            {
+                FindFinalNodeWithInheritDoc(xmlComment, key, xmlMembers);
+            }
+
             return xmlMembers;
         }
+
+		private static XmlCommentDescriptor FindFinalNodeWithInheritDoc(
+            XmlCommentDescriptor initialNode,
+            string initialKey,
+            Dictionary<string, XmlCommentDescriptor> xmlMembers
+        )
+		{
+			if (initialNode == null || string.IsNullOrEmpty(initialNode.InheritcDoc))
+			{
+				return initialNode;
+			}
+
+			var currentNode = initialNode;
+            var currentKey = initialKey;
+            var i = 0;
+			while (!string.IsNullOrEmpty(currentNode.InheritcDoc))
+			{
+				if (!xmlMembers.TryGetValue(currentNode.InheritcDoc, out var inheritedNode))
+				{
+					break;
+				}
+
+                currentNode = inheritedNode;
+                xmlMembers[currentKey] = inheritedNode;
+                currentKey = inheritedNode.InheritcDoc;
+
+                // Prevent infinite loop
+                if (i++ > 100)
+                {
+                    return initialNode;
+                }
+			}
+
+			return currentNode;
+		}
     }
 }
diff --git a/src/DotSwashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentDescriptor.cs b/src/DotSwashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentDescriptor.cs
@@ -7,6 +7,7 @@ public record XmlCommentDescriptor
         public string Summary { get; set; }
         public string Remarks { get; set; }
         public string Example { get; set; }
+        public string InheritcDoc { get; set; }
         public List<XmlParam> Params { get; set; }
         public List<XmlResponse> Responses { get; set; }
 

diff --git a/test/DotSwashbuckle.AspNetCore.SwaggerGen.Test/DotSwashbuckle.AspNetCore.SwaggerGen.Test.xml b/test/DotSwashbuckle.AspNetCore.SwaggerGen.Test/DotSwashbuckle.AspNetCore.SwaggerGen.Test.xml
diff --git a/...ashbuckle.AspNetCore.SwaggerGen.Test/Fixtures/FakeControllerWithInfiniteLoopInheritDoc.cs b/...ashbuckle.AspNetCore.SwaggerGen.Test/Fixtures/FakeControllerWithInfiniteLoopInheritDoc.cs
@@ -0,0 +1,26 @@
+using System;
+
+namespace DotSwashbuckle.AspNetCore.SwaggerGen.Test
+{
+    /// <inheritdoc cref = "FakeControllerWithXmlComments" />
+    public class FakeControllerWithInfiniteLoopInheritDoc : FakeControllerWithXmlComments
+    {
+        /// <inheritdoc cref = "FakeControllerWithInfiniteLoopInheritDoc.ActionWithResponseTags"/>
+        public new void ActionWithSummaryAndRemarksTags()
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <inheritdoc cref = "FakeControllerWithInfiniteLoopInheritDoc.ActionWithSummaryAndRemarksTags"/>
+        public new void ActionWithParamTags(string param1, string param2)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <inheritdoc cref = "FakeControllerWithInfiniteLoopInheritDoc.ActionWithParamTags"/>
+        public new void ActionWithResponseTags()
+        {
+            throw new NotImplementedException();
+        }
+    }
+}
diff --git a/test/DotSwashbuckle.AspNetCore.SwaggerGen.Test/Fixtures/FakeControllerWithInheritDoc.cs b/test/DotSwashbuckle.AspNetCore.SwaggerGen.Test/Fixtures/FakeControllerWithInheritDoc.cs
@@ -0,0 +1,26 @@
+using System;
+
+namespace DotSwashbuckle.AspNetCore.SwaggerGen.Test
+{
+    /// <inheritdoc cref = "FakeControllerWithXmlComments" />
+    public class FakeControllerWithInheritDoc : FakeControllerWithXmlComments
+    {
+        /// <inheritdoc cref = "FakeControllerWithXmlComments.ActionWithSummaryAndRemarksTags"/>
+        public new void ActionWithSummaryAndRemarksTags()
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <inheritdoc cref = "FakeControllerWithXmlComments.ActionWithParamTags"/>
+        public new void ActionWithParamTags(string param1, string param2)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <inheritdoc cref = "FakeControllerWithXmlComments.ActionWithResponseTags"/>
+        public new void ActionWithResponseTags()
+        {
+            throw new NotImplementedException();
+        }
+    }
+}
diff --git a/...tSwashbuckle.AspNetCore.SwaggerGen.Test/Fixtures/FakeControllerWithRecursiveInheritDoc.cs b/...tSwashbuckle.AspNetCore.SwaggerGen.Test/Fixtures/FakeControllerWithRecursiveInheritDoc.cs
@@ -0,0 +1,26 @@
+using System;
+
+namespace DotSwashbuckle.AspNetCore.SwaggerGen.Test
+{
+    /// <inheritdoc cref = "FakeControllerWithXmlComments" />
+    public class FakeControllerWithRecursiveInheritDoc : FakeControllerWithXmlComments
+    {
+        /// <inheritdoc cref = "FakeControllerWithXmlComments.ActionWithSummaryAndRemarksTags"/>
+        public new void ActionWithSummaryAndRemarksTags()
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <inheritdoc cref = "FakeControllerWithRecursiveInheritDoc.ActionWithSummaryAndRemarksTags"/>
+        public new void ActionWithParamTags(string param1, string param2)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <inheritdoc cref = "FakeControllerWithRecursiveInheritDoc.ActionWithParamTags"/>
+        public new void ActionWithResponseTags()
+        {
+            throw new NotImplementedException();
+        }
+    }
+}
diff --git a/test/DotSwashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsDocumentFilterTests.cs b/test/DotSwashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsDocumentFilterTests.cs
@@ -6,13 +6,18 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.OpenApi.Models;
 using Xunit;
+using DotSwashbuckle.AspNetCore.SwaggerGen.Test.Fixtures;
+using System;
 
 namespace DotSwashbuckle.AspNetCore.SwaggerGen.Test
 {
     public class XmlCommentsDocumentFilterTests
     {
-        [Fact]
-        public void Apply_SetsTagDescription_FromControllerSummaryTags()
+        [Theory]
+        [InlineData(typeof(FakeControllerWithXmlComments))]
+        [InlineData(typeof(FakeControllerWithInheritDoc))]
+        [InlineData(typeof(FakeControllerWithRecursiveInheritDoc))]
+        public void Apply_SetsTagDescription_FromControllerSummaryTags(Type fakeController)
         {
             var document = new OpenApiDocument();
             var filterContext = new DocumentFilterContext(
@@ -22,16 +27,50 @@ public void Apply_SetsTagDescription_FromControllerSummaryTags()
                     {
                         ActionDescriptor = new ControllerActionDescriptor
                         {
-                            ControllerTypeInfo = typeof(FakeControllerWithXmlComments).GetTypeInfo(),
-                            ControllerName = nameof(FakeControllerWithXmlComments)
+                            ControllerTypeInfo = fakeController.GetTypeInfo(),
+                            ControllerName = nameof(fakeController)
                         }
                     },
                     new ApiDescription
                     {
                         ActionDescriptor = new ControllerActionDescriptor
                         {
-                            ControllerTypeInfo = typeof(FakeControllerWithXmlComments).GetTypeInfo(),
-                            ControllerName = nameof(FakeControllerWithXmlComments)
+                            ControllerTypeInfo = fakeController.GetTypeInfo(),
+                            ControllerName = nameof(fakeController)
+                        }
+                    }
+                },
+                null,
+                null);
+
+            Subject().Apply(document, filterContext);
+
+            Assert.Equal(1, document.Tags.Count);
+            Assert.Equal("Summary for FakeControllerWithXmlComments", document.Tags[0].Description);
+        }
+
+        [Theory]
+        [InlineData(typeof(FakeControllerWithInfiniteLoopInheritDoc))]
+        public void Apply_InfiniteLoopOnInheritDoc_StopsAndResultNull(Type fakeController)
+        {
+            var document = new OpenApiDocument();
+            var filterContext = new DocumentFilterContext(
+                new[]
+                {
+                    new ApiDescription
+                    {
+                        ActionDescriptor = new ControllerActionDescriptor
+                        {
+                            ControllerTypeInfo = fakeController.GetTypeInfo(),
+                            ControllerName = nameof(fakeController)
+                        }
+                    },
+                    new ApiDescription
+                    {
+                        ActionDescriptor = new ControllerActionDescriptor
+                        {
+                            ControllerTypeInfo = fakeController.GetTypeInfo(),
+                            ControllerName = nameof(fakeController)
                         }
                     }
                 },