Improve hub primary tag selection using doc-level tags

The SignalR OpenAPI plugin now determines each hub's primary tag
based on the document-level tags array, ensuring the connection
bar appears above the first visible tag section in Swagger UI.
A fallback is provided for tags not listed in the array.
An integration test was added to verify this behavior.

Author: icnocop

src/SignalR.OpenApi.SwaggerUi/Resources/signalr-openapi-plugin.js

@@ -454,7 +454,6 @@ var SignalROpenApiPlugin = function (system) {
     }
 
     var tagMap = {};
-    var hubPrimaryTag = {};
     var pathsIm = specIm.get("paths");
     if (pathsIm) {
       pathsIm.keySeq().forEach(function (path) {
@@ -483,16 +482,38 @@ var SignalROpenApiPlugin = function (system) {
               var tagStr = typeof tag === "string" ? tag : (tag.get ? tag.get("name") || tag : tag);
               if (typeof tagStr === "string" && !tagMap[tagStr]) {
                 tagMap[tagStr] = hubPath;
-                if (!hubPrimaryTag[hubPath]) {
-                  hubPrimaryTag[hubPath] = tagStr;
-                }
               }
             });
           }
         }
       });
     }
 
+    // Determine the primary tag per hub using the document-level tags
+    // array, which defines the order SwaggerUI renders tag sections.
+    // This ensures the connection bar appears above the first visible
+    // tag section for each hub, not at a path-scan-order position.
+    var hubPrimaryTag = {};
+    var docTagsIm = specIm.get("tags");
+    if (docTagsIm) {
+      docTagsIm.forEach(function (tagObj) {
+        var name = tagObj && typeof tagObj.get === "function"
+          ? tagObj.get("name")
+          : (typeof tagObj === "string" ? tagObj : null);
+        if (name && tagMap[name] && !hubPrimaryTag[tagMap[name]]) {
+          hubPrimaryTag[tagMap[name]] = name;
+        }
+      });
+    }
+
+    // Fallback for tags not listed in the document-level tags array
+    Object.keys(tagMap).forEach(function (tag) {
+      var hp = tagMap[tag];
+      if (!hubPrimaryTag[hp]) {
+        hubPrimaryTag[hp] = tag;
+      }
+    });
+
     _cachedTagHubMapVersion = specIm;
     _cachedTagHubMap = tagMap;
     _cachedHubPrimaryTag = hubPrimaryTag;

test/SignalR.OpenApi.Tests/SwaggerUiIntegrationTests.cs

@@ -566,6 +566,25 @@ public async Task PluginJs_ContainsPrimaryTagDeduplication()
         Assert.IsTrue(content.Contains("_cachedHubPrimaryTag"), "Plugin JS should cache the primary tag per hub path");
     }
 
+    /// <summary>
+    /// Verifies that the plugin JS determines the primary tag per hub using
+    /// the document-level tags array so the connection bar renders above
+    /// the first visible tag section in SwaggerUI.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous test.</returns>
+    [TestMethod]
+    public async Task PluginJs_DeterminesPrimaryTagFromDocumentTagsArray()
+    {
+        using var host = await CreateTestHost();
+        using var client = host.GetTestClient();
+
+        using var response = await client.GetAsync("/signalr-swagger/_resources/signalr-openapi-plugin.js");
+        var content = await response.Content.ReadAsStringAsync();
+
+        Assert.IsTrue(content.Contains("specIm.get(\"tags\")"), "Plugin JS should read the document-level tags array for primary tag ordering");
+        Assert.IsTrue(content.Contains("tagObj.get(\"name\")"), "Plugin JS should extract tag names from the document tags array");
+    }
+
     /// <summary>
     /// Verifies that the CSS contains connection bar styles.
     /// </summary>