Add document-level OpenAPI tag descriptions support

- Collect all unique tags from hub methods and client events and add them to the OpenAPI document's tags section.
- Support tag descriptions via options.TagDescriptions or fallback to hub XML <summary> when tag matches hub name.
- Include client event tags (e.g., "Chat Events") in document tags.
- Update README with tag grouping/description docs and usage examples.
- Update sample code to demonstrate [Tags] and TagDescriptions usage.
- Add unit tests for tag collection, deduplication, and description resolution.
- Add TagDescriptions property to SignalROpenApiOptions.
- Refactor generator to centralize tag collection and description logic.

Author: icnocop

README.md

@@ -12,6 +12,7 @@ OpenAPI 3.1 specification generation and SwaggerUI support for ASP.NET Core Sign
 - **Streaming support**: `IAsyncEnumerable<T>` and `ChannelReader<T>` with accumulated item history and stream state tracking
 - **Client event monitoring**: Auto-subscribes to typed hub (`Hub<TClient>`) events with real-time event log panel
 - Supports standard ASP.NET Core attributes (`[Authorize]`, `[Tags]`, `[EndpointSummary]`, `[Obsolete]`, etc.)
+- Document-level tag definitions with descriptions (from options or XML summary fallback)
 - XML documentation comments for descriptions and examples
 - `[JsonPolymorphic]` / `[JsonDerivedType]` polymorphic schema support with OData-style sub-endpoints
 - Data Annotation validation attributes mapped to OpenAPI schema constraints
@@ -65,6 +66,10 @@ builder.Services.AddSignalROpenApi(options =>
     // Include type discriminator in JSON examples for polymorphic sub-endpoints (default: true)
     options.IncludeDiscriminatorInExamples = true;
 
+    // Add descriptions for tags (displayed as group descriptions in SwaggerUI)
+    options.TagDescriptions["Chat"] = "Real-time chat operations";
+    options.TagDescriptions["Chat Events"] = "Server-to-client chat notifications";
+
     // Configure JSON property naming (default: camelCase)
     options.JsonSerializerOptions = new System.Text.Json.JsonSerializerOptions
     {
@@ -167,7 +172,7 @@ public class AlertNotification : Notification
 
 | Attribute | OpenAPI Mapping |
 |-----------|----------------|
-| `[Tags("group")]` | `tags` on operation |
+| `[Tags("group")]` | `tags` on operation + document-level tag definition |
 | `[EndpointSummary("...")]` | `summary` on operation |
 | `[EndpointDescription("...")]` | `description` on operation |
 | `[EndpointName("Name")]` | `operationId` on operation |
@@ -184,6 +189,46 @@ public class AlertNotification : Notification
 | `[SignalROpenApiRequestExamples]` | Named request examples |
 | `[SignalROpenApiResponseExamples]` | Named response examples |
 
+## Tag Grouping
+
+Operations are grouped by tags in SwaggerUI. The generator automatically collects all unique tags from operations and adds them to the document-level `tags` section.
+
+### Tag Descriptions
+
+Tag descriptions appear as group headers in SwaggerUI. There are two ways to provide them:
+
+**1. Via options** (explicit):
+
+```csharp
+builder.Services.AddSignalROpenApi(options =>
+{
+    options.TagDescriptions["Chat"] = "Real-time chat operations";
+    options.TagDescriptions["Admin"] = "Administrative hub methods";
+});
+```
+
+**2. Via XML summary** (automatic fallback): When a tag name matches the hub name (e.g., tag `"Chat"` matches `ChatHub`), the hub's XML `<summary>` is used as the tag description automatically.
+
+```csharp
+/// <summary>
+/// Real-time chat operations.
+/// </summary>
+public class ChatHub : Hub
+{
+    // Methods default to the "Chat" tag → description comes from XML summary above
+}
+```
+
+Explicit `TagDescriptions` always take precedence over XML summary fallback.
+
+### Tag Sources
+
+| Source | Tag Name |
+|--------|----------|
+| Hub class (default) | Hub name without `Hub` suffix (e.g., `ChatHub` → `"Chat"`) |
+| `[Tags("group")]` on hub class or method | Specified tag name |
+| Client events (`Hub<TClient>`) | `"{HubName} Events"` (e.g., `"Chat Events"`) |
+
 ## Request Body Schema
 
 Hub method parameters are mapped to the OpenAPI request body schema:

samples/SignalR.OpenApi.Sample/Hubs/ChatHub.cs

@@ -34,12 +34,14 @@ public async Task ReplyToMessageAsync(ChatMessage originalMessage, ChatMessage r
     }
 
     /// <inheritdoc />
+    [Tags("Groups")]
     public async Task SendToGroupAsync(string group, string user, string message)
     {
         await this.Clients.Group(group).ReceiveMessage(user, message);
     }
 
     /// <inheritdoc />
+    [Tags("Notifications")]
     [SignalROpenApiRequestExamples(typeof(NotificationExamplesProvider))]
     public async Task SendNotificationAsync(Notification notification)
     {
@@ -55,6 +57,7 @@ public async Task SendNotificationAsync(Notification notification)
     }
 
     /// <inheritdoc />
+    [Tags("Streaming")]
     public async IAsyncEnumerable<int> Countdown(
         int from,
         [EnumeratorCancellation] CancellationToken cancellationToken)

samples/SignalR.OpenApi.Sample/Program.cs

@@ -18,6 +18,13 @@
     options.DocumentVersion = "v1";
     options.IncludeDiscriminatorInExamples = true;
 
+    // Tag descriptions shown as group headers in SwaggerUI
+    options.TagDescriptions["Chat"] = "Real-time chat operations including messaging, notifications, and streaming.";
+    options.TagDescriptions["Groups"] = "Send messages to specific SignalR groups.";
+    options.TagDescriptions["Notifications"] = "Polymorphic notification delivery (text and alert types).";
+    options.TagDescriptions["Streaming"] = "Server-to-client streaming operations.";
+    options.TagDescriptions["Chat Events"] = "Server-to-client callbacks. Subscribe to receive real-time notifications.";
+
     // Default: camelCase (matches ASP.NET Core default)
     // For PascalCase:
     options.JsonSerializerOptions.PropertyNamingPolicy = null;

src/SignalR.OpenApi/Generation/SignalROpenApiDocumentGenerator.cs

@@ -79,6 +79,8 @@ public OpenApiDocument GenerateDocument(IReadOnlyList<SignalRHubInfo> hubs)
             AddSecuritySchemes(document);
         }
 
+        this.AddDocumentTags(document, hubs);
+
         return document;
     }
 
@@ -376,6 +378,80 @@ private static Microsoft.OpenApi.Any.OpenApiArray ConvertJsonArray(JsonElement e
         return arr;
     }
 
+    /// <summary>
+    /// Collects every unique tag referenced by operations and adds
+    /// document-level tag definitions with optional descriptions.
+    /// Descriptions are resolved from <see cref="SignalROpenApiOptions.TagDescriptions"/>
+    /// first, then fall back to the hub's XML summary when the tag name
+    /// matches the hub name.
+    /// </summary>
+    private void AddDocumentTags(OpenApiDocument document, IReadOnlyList<SignalRHubInfo> hubs)
+    {
+        // Build a lookup of hub name → summary for fallback descriptions.
+        var hubSummaries = new Dictionary<string, string>(StringComparer.Ordinal);
+        foreach (var hub in hubs)
+        {
+            if (!string.IsNullOrWhiteSpace(hub.Summary))
+            {
+                hubSummaries.TryAdd(hub.Name, hub.Summary);
+            }
+        }
+
+        // Collect all unique tag names from operations, preserving first-seen order.
+        var tagNames = new List<string>();
+        var tagSet = new HashSet<string>(StringComparer.Ordinal);
+
+        foreach (var hub in hubs)
+        {
+            foreach (var method in hub.Methods)
+            {
+                foreach (var tag in method.Tags)
+                {
+                    if (tagSet.Add(tag))
+                    {
+                        tagNames.Add(tag);
+                    }
+                }
+            }
+
+            foreach (var clientEvent in hub.ClientEvents)
+            {
+                var eventTag = $"{hub.Name} Events";
+                if (tagSet.Add(eventTag))
+                {
+                    tagNames.Add(eventTag);
+                }
+            }
+        }
+
+        if (tagNames.Count == 0)
+        {
+            return;
+        }
+
+        document.Tags = new List<OpenApiTag>();
+
+        foreach (var tagName in tagNames)
+        {
+            string? description = null;
+
+            if (this.options.TagDescriptions.TryGetValue(tagName, out var configured))
+            {
+                description = configured;
+            }
+            else if (hubSummaries.TryGetValue(tagName, out var hubSummary))
+            {
+                description = hubSummary;
+            }
+
+            document.Tags.Add(new OpenApiTag
+            {
+                Name = tagName,
+                Description = description,
+            });
+        }
+    }
+
     private string ConvertPropertyName(string value)
     {
         var policy = this.options.JsonSerializerOptions.PropertyNamingPolicy;

src/SignalR.OpenApi/SignalROpenApiOptions.cs

@@ -71,6 +71,14 @@ public sealed class SignalROpenApiOptions
     /// </summary>
     public bool IncludeDiscriminatorInExamples { get; set; } = true;
 
+    /// <summary>
+    /// Gets or sets descriptions for OpenAPI tags. Maps tag names to their
+    /// descriptions, which appear in the document-level <c>tags</c> section.
+    /// When a tag used by an operation is not present here, the generator
+    /// falls back to the hub's XML summary if the tag name matches the hub name.
+    /// </summary>
+    public IDictionary<string, string> TagDescriptions { get; set; } = new Dictionary<string, string>(StringComparer.Ordinal);
+
     /// <summary>
     /// Gets or sets the <see cref="JsonSerializerOptions"/> used for property naming
     /// and example serialization in the generated OpenAPI document.

test/SignalR.OpenApi.Tests/SignalROpenApiDocumentGeneratorTests.cs

@@ -984,6 +984,121 @@ public void GenerateDocument_WhenJsonStringEnumConverterConfiguredThenEnumProper
         Assert.AreEqual("string", statusProp.Type, "Status property should be string with JsonStringEnumConverter.");
     }
 
+    /// <summary>
+    /// Verifies the document-level tags list contains all unique tags from operations.
+    /// </summary>
+    [TestMethod]
+    public void GenerateDocument_PopulatesDocumentLevelTags()
+    {
+        var (discoverer, generator) = CreateServices();
+        var hubs = discoverer.DiscoverHubs();
+        var doc = generator.GenerateDocument(hubs);
+
+        Assert.IsNotNull(doc.Tags, "Document should have tags.");
+        Assert.IsTrue(doc.Tags.Count > 0, "Document should have at least one tag.");
+
+        var tagNames = doc.Tags.Select(t => t.Name).ToList();
+
+        // BasicHub has no [Tags] so its methods default to "Basic" tag
+        CollectionAssert.Contains(tagNames, "Basic");
+
+        // AttributeHub methods without [Tags] default to hub name "Attribute"
+        CollectionAssert.Contains(tagNames, "Attribute");
+
+        // GetUserDetailsAsync on AttributeHub uses [Tags("Users")]
+        CollectionAssert.Contains(tagNames, "Users");
+    }
+
+    /// <summary>
+    /// Verifies that tag descriptions configured via options are applied.
+    /// </summary>
+    [TestMethod]
+    public void GenerateDocument_WhenTagDescriptionConfiguredThenApplied()
+    {
+        var (discoverer, generator) = CreateServices(o =>
+        {
+            o.TagDescriptions["Basic"] = "Basic hub operations";
+        });
+
+        var hubs = discoverer.DiscoverHubs();
+        var doc = generator.GenerateDocument(hubs);
+
+        Assert.IsNotNull(doc.Tags);
+        var basicTag = doc.Tags.FirstOrDefault(t => t.Name == "Basic");
+        Assert.IsNotNull(basicTag, "Document should contain a 'Basic' tag.");
+        Assert.AreEqual("Basic hub operations", basicTag.Description);
+    }
+
+    /// <summary>
+    /// Verifies that when no description is configured, the hub's XML summary
+    /// is used as fallback when the tag name matches the hub name.
+    /// </summary>
+    [TestMethod]
+    public void GenerateDocument_WhenNoTagDescriptionThenFallsBackToHubSummary()
+    {
+        var (discoverer, generator) = CreateServices();
+        var hubs = discoverer.DiscoverHubs();
+        var doc = generator.GenerateDocument(hubs);
+
+        Assert.IsNotNull(doc.Tags);
+
+        // BasicHub has XML summary "A basic hub for testing." and default tag "Basic"
+        var basicTag = doc.Tags.FirstOrDefault(t => t.Name == "Basic");
+        Assert.IsNotNull(basicTag, "Document should contain a 'Basic' tag.");
+        Assert.AreEqual("A basic hub for testing.", basicTag.Description);
+    }
+
+    /// <summary>
+    /// Verifies that configured tag descriptions take precedence over hub XML summaries.
+    /// </summary>
+    [TestMethod]
+    public void GenerateDocument_WhenTagDescriptionConfiguredThenOverridesHubSummary()
+    {
+        var (discoverer, generator) = CreateServices(o =>
+        {
+            o.TagDescriptions["Basic"] = "Custom description";
+        });
+
+        var hubs = discoverer.DiscoverHubs();
+        var doc = generator.GenerateDocument(hubs);
+
+        Assert.IsNotNull(doc.Tags);
+        var basicTag = doc.Tags.FirstOrDefault(t => t.Name == "Basic");
+        Assert.IsNotNull(basicTag, "Document should contain a 'Basic' tag.");
+        Assert.AreEqual("Custom description", basicTag.Description);
+    }
+
+    /// <summary>
+    /// Verifies that tags from client events (e.g., "TypedChat Events") appear in document tags.
+    /// </summary>
+    [TestMethod]
+    public void GenerateDocument_IncludesClientEventTags()
+    {
+        var (discoverer, generator) = CreateServices();
+        var hubs = discoverer.DiscoverHubs();
+        var doc = generator.GenerateDocument(hubs);
+
+        Assert.IsNotNull(doc.Tags);
+        var tagNames = doc.Tags.Select(t => t.Name).ToList();
+        CollectionAssert.Contains(tagNames, "TypedChat Events");
+    }
+
+    /// <summary>
+    /// Verifies that document tags are deduplicated when multiple methods share the same tag.
+    /// </summary>
+    [TestMethod]
+    public void GenerateDocument_DeduplicatesDocumentTags()
+    {
+        var (discoverer, generator) = CreateServices();
+        var hubs = discoverer.DiscoverHubs();
+        var doc = generator.GenerateDocument(hubs);
+
+        Assert.IsNotNull(doc.Tags);
+        var tagNames = doc.Tags.Select(t => t.Name).ToList();
+        var distinctNames = tagNames.Distinct().ToList();
+        Assert.AreEqual(distinctNames.Count, tagNames.Count, "Document tags should be unique.");
+    }
+
     private static (ReflectionHubDiscoverer Discoverer, SignalROpenApiDocumentGenerator Generator) CreateServices(
         Action<SignalROpenApiOptions>? configure = null)
     {