Add doc expansion and sorting options to Swagger UI

Introduce DocExpansion enum and new options to control tag/operation expansion and sorting in SignalR Swagger UI. Update DI, middleware, and README to support DocExpansion, SortTagsAlphabetically, and SortOperationsAlphabetically. Add integration tests to verify configuration and UI output.

Author: icnocop

README.md

@@ -92,6 +92,9 @@ builder.Services.AddSignalRSwaggerUi(options =>
     options.StripAsyncSuffix = true;             // Strip "Async" from display names (default)
     options.SyntaxHighlight = true;              // Enable syntax highlighting (default)
     options.DefaultModelsExpandDepth = -1;       // Hide models section (default), 1 to show
+    options.DocExpansion = DocExpansion.List;     // Tag expand mode: List (default), Full, None
+    options.SortTagsAlphabetically = false;      // Sort tags A-Z (default: document order)
+    options.SortOperationsAlphabetically = false; // Sort operations A-Z (default: document order)
 
     // Static headers sent with every SignalR hub connection
     options.Headers["X-Custom-Header"] = "MyValue";

src/SignalR.OpenApi.SwaggerUi/DocExpansion.cs

@@ -0,0 +1,25 @@
+// Copyright (c) SignalR.OpenApi Contributors. Licensed under the MIT License.
+
+namespace SignalR.OpenApi.SwaggerUi;
+
+/// <summary>
+/// Controls the default expansion setting for the operations and tags in SwaggerUI.
+/// </summary>
+public enum DocExpansion
+{
+    /// <summary>
+    /// Expands only the tags (groups). Operations within each tag are collapsed.
+    /// This is the default SwaggerUI behavior.
+    /// </summary>
+    List,
+
+    /// <summary>
+    /// Expands the tags and operations fully.
+    /// </summary>
+    Full,
+
+    /// <summary>
+    /// Collapses everything (both tags and operations).
+    /// </summary>
+    None,
+}

src/SignalR.OpenApi.SwaggerUi/Extensions/SwaggerUiApplicationBuilderExtensions.cs

@@ -68,6 +68,21 @@ public static IApplicationBuilder UseSignalRSwaggerUi(
             // Set default models expand depth
             c.DefaultModelsExpandDepth(options.DefaultModelsExpandDepth);
 
+            // Set doc expansion mode
+            c.DocExpansion((Swashbuckle.AspNetCore.SwaggerUI.DocExpansion)options.DocExpansion);
+
+            // Sort tags alphabetically if configured
+            if (options.SortTagsAlphabetically)
+            {
+                c.ConfigObject.AdditionalItems["tagsSorter"] = "alpha";
+            }
+
+            // Sort operations alphabetically if configured
+            if (options.SortOperationsAlphabetically)
+            {
+                c.ConfigObject.AdditionalItems["operationsSorter"] = "alpha";
+            }
+
             // Configure auth UI for JWT Bearer (standard SwaggerUI behavior)
             c.OAuthUsePkce();
         });

src/SignalR.OpenApi.SwaggerUi/Extensions/SwaggerUiServiceCollectionExtensions.cs

@@ -32,6 +32,9 @@ public static IServiceCollection AddSignalRSwaggerUi(
             o.StripAsyncSuffix = options.StripAsyncSuffix;
             o.SyntaxHighlight = options.SyntaxHighlight;
             o.DefaultModelsExpandDepth = options.DefaultModelsExpandDepth;
+            o.DocExpansion = options.DocExpansion;
+            o.SortTagsAlphabetically = options.SortTagsAlphabetically;
+            o.SortOperationsAlphabetically = options.SortOperationsAlphabetically;
 
             foreach (var header in options.Headers)
             {

src/SignalR.OpenApi.SwaggerUi/SignalRSwaggerUiOptions.cs

@@ -51,6 +51,26 @@ public class SignalRSwaggerUiOptions
     /// </summary>
     public int DefaultModelsExpandDepth { get; set; } = -1;
 
+    /// <summary>
+    /// Gets or sets the default expansion setting for tags and operations in SwaggerUI.
+    /// Defaults to <see cref="SwaggerUi.DocExpansion.List"/> (tags expanded, operations collapsed).
+    /// </summary>
+    public DocExpansion DocExpansion { get; set; } = DocExpansion.List;
+
+    /// <summary>
+    /// Gets or sets a value indicating whether tags (groups) are sorted
+    /// alphabetically in SwaggerUI. Defaults to <see langword="false"/>
+    /// (tags appear in the order defined by the OpenAPI document).
+    /// </summary>
+    public bool SortTagsAlphabetically { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether operations (endpoints)
+    /// within each tag are sorted alphabetically in SwaggerUI.
+    /// Defaults to <see langword="false"/> (operations appear in document order).
+    /// </summary>
+    public bool SortOperationsAlphabetically { get; set; }
+
     /// <summary>
     /// Gets the custom HTTP headers to include on every SignalR hub connection.
     /// These headers are sent with the initial negotiate request and all long-polling

test/SignalR.OpenApi.Tests/SwaggerUiIntegrationTests.cs

@@ -58,6 +58,9 @@ public void AddSignalRSwaggerUi_DefaultOptions()
         Assert.AreEqual(0, options.Headers.Count);
         Assert.IsTrue(options.SyntaxHighlight);
         Assert.AreEqual(-1, options.DefaultModelsExpandDepth);
+        Assert.AreEqual(DocExpansion.List, options.DocExpansion);
+        Assert.IsFalse(options.SortTagsAlphabetically);
+        Assert.IsFalse(options.SortOperationsAlphabetically);
     }
 
     /// <summary>
@@ -117,6 +120,60 @@ public void AddSignalRSwaggerUi_CustomDefaultModelsExpandDepth()
         Assert.AreEqual(2, options.DefaultModelsExpandDepth);
     }
 
+    /// <summary>
+    /// Verifies that DocExpansion can be configured via DI.
+    /// </summary>
+    [TestMethod]
+    public void AddSignalRSwaggerUi_CustomDocExpansion()
+    {
+        var services = new ServiceCollection();
+        services.AddSignalRSwaggerUi(o =>
+        {
+            o.DocExpansion = DocExpansion.None;
+        });
+
+        using var provider = services.BuildServiceProvider();
+        var options = provider.GetRequiredService<IOptions<SignalRSwaggerUiOptions>>().Value;
+
+        Assert.AreEqual(DocExpansion.None, options.DocExpansion);
+    }
+
+    /// <summary>
+    /// Verifies that SortTagsAlphabetically can be configured via DI.
+    /// </summary>
+    [TestMethod]
+    public void AddSignalRSwaggerUi_SortTagsAlphabetically()
+    {
+        var services = new ServiceCollection();
+        services.AddSignalRSwaggerUi(o =>
+        {
+            o.SortTagsAlphabetically = true;
+        });
+
+        using var provider = services.BuildServiceProvider();
+        var options = provider.GetRequiredService<IOptions<SignalRSwaggerUiOptions>>().Value;
+
+        Assert.IsTrue(options.SortTagsAlphabetically);
+    }
+
+    /// <summary>
+    /// Verifies that SortOperationsAlphabetically can be configured via DI.
+    /// </summary>
+    [TestMethod]
+    public void AddSignalRSwaggerUi_SortOperationsAlphabetically()
+    {
+        var services = new ServiceCollection();
+        services.AddSignalRSwaggerUi(o =>
+        {
+            o.SortOperationsAlphabetically = true;
+        });
+
+        using var provider = services.BuildServiceProvider();
+        var options = provider.GetRequiredService<IOptions<SignalRSwaggerUiOptions>>().Value;
+
+        Assert.IsTrue(options.SortOperationsAlphabetically);
+    }
+
     /// <summary>
     /// Verifies embedded signalr.min.js resource is served.
     /// </summary>
@@ -284,6 +341,102 @@ public async Task SwaggerUi_CustomDefaultModelsExpandDepthApplied()
         Assert.IsTrue(content.Contains("defaultModelsExpandDepth"), "Config should include defaultModelsExpandDepth");
     }
 
+    /// <summary>
+    /// Verifies that DocExpansion defaults to "list" in the SwaggerUI configObject.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous test.</returns>
+    [TestMethod]
+    public async Task SwaggerUi_DocExpansionDefaultIsList()
+    {
+        using var host = await CreateTestHost();
+        using var client = host.GetTestClient();
+
+        using var response = await client.GetAsync("/signalr-swagger/index.js");
+        var content = await response.Content.ReadAsStringAsync();
+
+        Assert.IsTrue(content.Contains("\"docExpansion\":\"list\""), "Default DocExpansion should be list");
+    }
+
+    /// <summary>
+    /// Verifies that DocExpansion.None is applied to the SwaggerUI configObject.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous test.</returns>
+    [TestMethod]
+    public async Task SwaggerUi_DocExpansionNoneApplied()
+    {
+        using var host = await CreateTestHost(o => o.DocExpansion = DocExpansion.None);
+        using var client = host.GetTestClient();
+
+        using var response = await client.GetAsync("/signalr-swagger/index.js");
+        var content = await response.Content.ReadAsStringAsync();
+
+        Assert.IsTrue(content.Contains("\"docExpansion\":\"none\""), "DocExpansion should be none");
+    }
+
+    /// <summary>
+    /// Verifies that tagsSorter is not present by default.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous test.</returns>
+    [TestMethod]
+    public async Task SwaggerUi_TagsSorterNotPresentByDefault()
+    {
+        using var host = await CreateTestHost();
+        using var client = host.GetTestClient();
+
+        using var response = await client.GetAsync("/signalr-swagger/index.js");
+        var content = await response.Content.ReadAsStringAsync();
+
+        Assert.IsFalse(content.Contains("tagsSorter"), "tagsSorter should not be present by default");
+    }
+
+    /// <summary>
+    /// Verifies that tagsSorter is set to "alpha" when SortTagsAlphabetically is true.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous test.</returns>
+    [TestMethod]
+    public async Task SwaggerUi_SortTagsAlphabeticallyApplied()
+    {
+        using var host = await CreateTestHost(o => o.SortTagsAlphabetically = true);
+        using var client = host.GetTestClient();
+
+        using var response = await client.GetAsync("/signalr-swagger/index.js");
+        var content = await response.Content.ReadAsStringAsync();
+
+        Assert.IsTrue(content.Contains("\"tagsSorter\":\"alpha\""), "tagsSorter should be alpha when enabled");
+    }
+
+    /// <summary>
+    /// Verifies that operationsSorter is not present by default.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous test.</returns>
+    [TestMethod]
+    public async Task SwaggerUi_OperationsSorterNotPresentByDefault()
+    {
+        using var host = await CreateTestHost();
+        using var client = host.GetTestClient();
+
+        using var response = await client.GetAsync("/signalr-swagger/index.js");
+        var content = await response.Content.ReadAsStringAsync();
+
+        Assert.IsFalse(content.Contains("operationsSorter"), "operationsSorter should not be present by default");
+    }
+
+    /// <summary>
+    /// Verifies that operationsSorter is set to "alpha" when SortOperationsAlphabetically is true.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous test.</returns>
+    [TestMethod]
+    public async Task SwaggerUi_SortOperationsAlphabeticallyApplied()
+    {
+        using var host = await CreateTestHost(o => o.SortOperationsAlphabetically = true);
+        using var client = host.GetTestClient();
+
+        using var response = await client.GetAsync("/signalr-swagger/index.js");
+        var content = await response.Content.ReadAsStringAsync();
+
+        Assert.IsTrue(content.Contains("\"operationsSorter\":\"alpha\""), "operationsSorter should be alpha when enabled");
+    }
+
     /// <summary>
     /// Verifies that the document includes hubPath in x-signalr extension.
     /// </summary>