Support for associating XML Comments with custom tags defined using TagsAttribute

src/Swashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs

@@ -422,7 +422,9 @@ public static void DocumentFilter<TFilter>(
         /// <param name="xmlDocFactory">A factory method that returns XML Comments as an XPathDocument</param>
         /// <param name="includeControllerXmlComments">
         /// Flag to indicate if controller XML comments (i.e. summary) should be used to assign Tag descriptions.
-        /// Don't set this flag if you're customizing the default tag for operations via TagActionsBy.
+        /// If customizing the default tag for operations via TagsAttribute, only the first Tag per controller will be
+        /// associated with the description.
+        /// However, don't set this flag if you're customizing the default tag for operations via TagActionsBy.
         /// </param>
         public static void IncludeXmlComments(
             this SwaggerGenOptions swaggerGenOptions,
@@ -446,7 +448,9 @@ public static void IncludeXmlComments(
         /// <param name="filePath">An absolute path to the file that contains XML Comments</param>
         /// <param name="includeControllerXmlComments">
         /// Flag to indicate if controller XML comments (i.e. summary) should be used to assign Tag descriptions.
-        /// Don't set this flag if you're customizing the default tag for operations via TagActionsBy.
+        /// If customizing the default tag for operations via TagsAttribute, only the first Tag per controller will be
+        /// associated with the description.
+        /// However, don't set this flag if you're customizing the default tag for operations via TagActionsBy.
         /// </param>
         public static void IncludeXmlComments(
             this SwaggerGenOptions swaggerGenOptions,

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/KeyValuePairExtensions.cs

@@ -0,0 +1,14 @@
+using System.Collections.Generic;
+
+namespace Swashbuckle.AspNetCore.SwaggerGen
+{
+    public static class KeyValuePairExtensions
+    {
+        // Explicit deconstruct required for older .NET frameworks
+        public static void Deconstruct<TKey, TValue>(this KeyValuePair<TKey, TValue> kvp, out TKey key, out TValue value)
+        {
+            key = kvp.Key;
+            value = kvp.Value;
+        }
+    }
+}

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsDocumentFilter.cs

@@ -4,6 +4,8 @@
 using Microsoft.AspNetCore.Mvc.Controllers;
 using Microsoft.OpenApi.Models;
 using System;
+using System.Reflection;
+using Microsoft.AspNetCore.Http;
 
 namespace Swashbuckle.AspNetCore.SwaggerGen
 {
@@ -21,34 +23,63 @@ public XmlCommentsDocumentFilter(XPathDocument xmlDoc)
 
         public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
         {
-            // Collect (unique) controller names and types in a dictionary
-            var controllerNamesAndTypes = context.ApiDescriptions
+            // Collect (unique) controller names, types and custom tags (defined by the first TagsAttribute value) in a dictionary
+            var controllers = context.ApiDescriptions
                 .Select(apiDesc => apiDesc.ActionDescriptor as ControllerActionDescriptor)
                 .Where(actionDesc => actionDesc != null)
                 .GroupBy(actionDesc => actionDesc.ControllerName)
-                .Select(group => new KeyValuePair<string, Type>(group.Key, group.First().ControllerTypeInfo.AsType()));
+                .Select(group => new KeyValuePair<string, ControllerInfo>(group.Key, GetControllerInfo(group)));
 
-            foreach (var nameAndType in controllerNamesAndTypes)
+            swaggerDoc.Tags ??= new List<OpenApiTag>();
+            foreach (var (controllerName, controllerInfo) in controllers)
             {
-                var memberName = XmlCommentsNodeNameHelper.GetMemberNameForType(nameAndType.Value);
+                var memberName = XmlCommentsNodeNameHelper.GetMemberNameForType(controllerInfo.ControllerType);
                 var typeNode = _xmlNavigator.SelectSingleNode(string.Format(MemberXPath, memberName));
 
-                if (typeNode != null)
+                var description = GetXmlDescriptionOrNull(typeNode);
+
+                swaggerDoc.Tags.Add(new OpenApiTag
                 {
-                    var summaryNode = typeNode.SelectSingleNode(SummaryTag);
-                    if (summaryNode != null)
-                    {
-                        if (swaggerDoc.Tags == null)
-                            swaggerDoc.Tags = new List<OpenApiTag>();
-
-                        swaggerDoc.Tags.Add(new OpenApiTag
-                        {
-                            Name = nameAndType.Key,
-                            Description = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml)
-                        });
-                    }
+                    Name = controllerInfo.CustomTagName ?? controllerName,
+                    Description = description
+                });
+            }
+            swaggerDoc.Tags = swaggerDoc.Tags.OrderBy(x => x.Name).ToList();
+        }
+
+        private class ControllerInfo
+        {
+            public Type ControllerType { get; set; }
+            public string CustomTagName { get; set; }
+        }
+
+        private static ControllerInfo GetControllerInfo(IGrouping<string, ControllerActionDescriptor> group)
+        {
+            var controllerInfo = new ControllerInfo
+            {
+                ControllerType = group.First().ControllerTypeInfo.AsType()
+            };
+
+#if NET6_0_OR_GREATER
+            controllerInfo.CustomTagName =
+                group.First().MethodInfo.DeclaringType?.GetCustomAttribute<TagsAttribute>()?.Tags[0];
+#endif
+
+            return controllerInfo;
+        }
+
+        private static string GetXmlDescriptionOrNull(XPathNavigator typeNode)
+        {
+            if (typeNode != null)
+            {
+                var summaryNode = typeNode.SelectSingleNode(SummaryTag);
+                if (summaryNode != null)
+                {
+                    return XmlCommentsTextHelper.Humanize(summaryNode.InnerXml);
                 }
             }
+
+            return null;
         }
     }
 }

test/Swashbuckle.AspNetCore.SwaggerGen.Test/Fixtures/FakeControllerWithCustomTagAndXmlSummary.cs

@@ -0,0 +1,17 @@
+using Microsoft.AspNetCore.Http;
+
+namespace Swashbuckle.AspNetCore.SwaggerGen.Test
+{
+    /// <summary>
+    /// Summary for FakeControllerWithCustomTag
+    /// </summary>
+    [Tags("fake controller custom tag")]
+    public class FakeControllerWithCustomTag
+    {
+        public void ActionAny()
+        { }
+
+        public void ActionAnother()
+        { }
+    }
+}

test/Swashbuckle.AspNetCore.SwaggerGen.Test/Fixtures/FakeControllerWithXmlComments.cs

@@ -1,7 +1,4 @@
-using Swashbuckle.AspNetCore.TestSupport;
-using System;
-
-namespace Swashbuckle.AspNetCore.SwaggerGen.Test
+namespace Swashbuckle.AspNetCore.SwaggerGen.Test
 {
     /// <summary>
     /// Summary for FakeControllerWithXmlComments

test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsDocumentFilterTests.cs

@@ -23,15 +23,17 @@
                         ActionDescriptor = new ControllerActionDescriptor
                         {
                             ControllerTypeInfo = typeof(FakeControllerWithXmlComments).GetTypeInfo(),
-                            ControllerName = nameof(FakeControllerWithXmlComments)
+                            ControllerName = nameof(FakeControllerWithXmlComments),
+                            MethodInfo = typeof(FakeControllerWithXmlComments).GetMethod(nameof(FakeControllerWithXmlComments.ActionWithParamTags))!
                         }
                     },
                     new ApiDescription
                     {
                         ActionDescriptor = new ControllerActionDescriptor
                         {
                             ControllerTypeInfo = typeof(FakeControllerWithXmlComments).GetTypeInfo(),
-                            ControllerName = nameof(FakeControllerWithXmlComments)
+                            ControllerName = nameof(FakeControllerWithXmlComments),
+                            MethodInfo = typeof(FakeControllerWithXmlComments).GetMethod(nameof(FakeControllerWithXmlComments.ActionWithParamTags))!
                         }
                     }
                 },
@@ -41,9 +43,91 @@
             Subject().Apply(document, filterContext);
 
             var tag = Assert.Single(document.Tags);
+            Assert.Equal("FakeControllerWithXmlComments", tag.Name);
             Assert.Equal("Summary for FakeControllerWithXmlComments", tag.Description);
         }
 
+        [Fact]
+        public void Apply_SetsCustomTagNameAndDescription_FromControllerAttributesAndSummaryTags()
+        {
+            var document = new OpenApiDocument();
+            var filterContext = new DocumentFilterContext(
+                new[]
+                {
+                    new ApiDescription
+                    {
+                        ActionDescriptor = new ControllerActionDescriptor
+                        {
+                            ControllerTypeInfo = typeof(FakeControllerWithCustomTag).GetTypeInfo(),
+                            ControllerName = nameof(FakeControllerWithCustomTag),
+                            MethodInfo = typeof(FakeControllerWithCustomTag).GetMethod(nameof(FakeControllerWithCustomTag.ActionAny))!
+                        }
+                    },
+                    new ApiDescription
+                    {
+                        ActionDescriptor = new ControllerActionDescriptor
+                        {
+                            ControllerTypeInfo = typeof(FakeControllerWithCustomTag).GetTypeInfo(),
+                            ControllerName = nameof(FakeControllerWithCustomTag),
+                            MethodInfo = typeof(FakeControllerWithCustomTag).GetMethod(nameof(FakeControllerWithCustomTag.ActionAnother))!
+                        }
+                    }
+                },
+                null,
+                null);
+
+            Subject().Apply(document, filterContext);
+
+            Assert.Equal(1, document.Tags.Count);
+            Assert.Equal("fake controller custom tag", document.Tags[0].Name);
+            Assert.Equal("Summary for FakeControllerWithCustomTag", document.Tags[0].Description);
+        }
+
+        [Fact]
+        public void Apply_SetsTagNameWithNoDescription_ForControllerWithoutSummaryTags()
+        {
+            var document = new OpenApiDocument();
+            var filterContext = new DocumentFilterContext(
+                new[]
+                {
+                    new ApiDescription
+                    {
+                        ActionDescriptor = new ControllerActionDescriptor
+                        {
+                            ControllerTypeInfo = typeof(FakeController).GetTypeInfo(),
+                            ControllerName = nameof(FakeController),
+                            MethodInfo = typeof(FakeController).GetMethod(nameof(FakeController.ActionWithParameter))!
+                        }
+                    },
+                    new ApiDescription
+                    {
+                        ActionDescriptor = new ControllerActionDescriptor
+                        {
+                            ControllerTypeInfo = typeof(FakeControllerWithCustomTag).GetTypeInfo(),
+                            ControllerName = nameof(FakeControllerWithCustomTag),
+                            MethodInfo = typeof(FakeControllerWithCustomTag).GetMethod(nameof(FakeControllerWithCustomTag.ActionAny))!
+                        }
+                    }
+                },
+                null,
+                null);
+
+            Subject().Apply(document, filterContext);
+
+            Assert.Equal(2, document.Tags.Count);
+            Assert.Collection(document.Tags,
+                tag1 =>
+                {
+                    Assert.Equal("fake controller custom tag", tag1.Name);
+                    Assert.Equal("Summary for FakeControllerWithCustomTag", tag1.Description);
+                },
+                tag2 =>
+                {
+                    Assert.Equal("FakeController", tag2.Name);
+                    Assert.Null(tag2.Description);
+                });
+        }
+
         private static XmlCommentsDocumentFilter Subject()
         {
             using (var xmlComments = File.OpenText($"{typeof(FakeControllerWithXmlComments).Assembly.GetName().Name}.xml"))