Respect tagsSorter for hub primary tag selection

Update signalr-openapi-plugin.js to select the primary tag per hub based on the SwaggerUI tagsSorter config: use alphabetical order when tagsSorter is "alpha", otherwise use document tag order. Move fallback logic for missing tags to apply only in document order mode. Add a test to verify alphabetical sorting logic is present in the plugin JS.

Author: icnocop

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

@@ -489,31 +489,47 @@ var SignalROpenApiPlugin = function (system) {
       });
     }
 
-    // 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.
+    // Determine the primary tag per hub — the first tag SwaggerUI
+    // actually renders for each hub. When tagsSorter is "alpha",
+    // SwaggerUI sorts tags alphabetically, overriding document order.
+    // Otherwise the document-level tags array defines render order.
     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;
+    var configs = system.getConfigs ? system.getConfigs() : {};
+    if (configs.tagsSorter === "alpha") {
+      // Alphabetical sort: pick the lexicographically first tag per hub
+      var sortedTags = Object.keys(tagMap).sort(function (a, b) {
+        return a.localeCompare(b);
+      });
+      for (var si = 0; si < sortedTags.length; si++) {
+        var hp = tagMap[sortedTags[si]];
+        if (!hubPrimaryTag[hp]) {
+          hubPrimaryTag[hp] = sortedTags[si];
+        }
+      }
+    } else {
+      // Document order: iterate the document-level tags array which
+      // matches the order SwaggerUI renders tag sections by default.
+      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;
         }
       });
     }
 
-    // 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

@@ -585,6 +585,25 @@ public async Task PluginJs_DeterminesPrimaryTagFromDocumentTagsArray()
         Assert.IsTrue(content.Contains("tagObj.get(\"name\")"), "Plugin JS should extract tag names from the document tags array");
     }
 
+    /// <summary>
+    /// Verifies that the plugin JS uses alphabetical sorting for the primary
+    /// tag when tagsSorter is "alpha", so the connection bar renders above
+    /// the first alphabetically-sorted tag section for each hub.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous test.</returns>
+    [TestMethod]
+    public async Task PluginJs_UsesAlphabeticalPrimaryTagWhenTagsSorterAlpha()
+    {
+        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("configs.tagsSorter === \"alpha\""), "Plugin JS should check tagsSorter config for alphabetical sorting");
+        Assert.IsTrue(content.Contains("localeCompare"), "Plugin JS should sort tags alphabetically when tagsSorter is alpha");
+    }
+
     /// <summary>
     /// Verifies that the CSS contains connection bar styles.
     /// </summary>