Improve XML doc inheritdoc support & UI Async suffix handling

Enhance SignalR.OpenApi to resolve XML docs via <inheritdoc /> for hub methods, inheriting summaries, remarks, param, and return docs from interfaces. Add IChatHub interface and update ChatHub to use <inheritdoc />. Add test hubs and tests for inheritdoc resolution. Add options for property naming and discriminator visibility in JSON examples. "Async" suffix is now stripped only in UI display, not in operation IDs or method names. Update README and sample code to reflect these features.

Author: icnocop

README.md

@@ -61,14 +61,23 @@ builder.Services.AddSignalROpenApi(options =>
 {
     options.DocumentTitle = "My SignalR API";
     options.DocumentVersion = "v1";
-    options.StripAsyncSuffix = true;
+
+    // Include type discriminator in JSON examples for polymorphic sub-endpoints (default: true)
+    options.IncludeDiscriminatorInExamples = true;
+
+    // Configure JSON property naming (default: camelCase)
+    options.JsonSerializerOptions = new System.Text.Json.JsonSerializerOptions
+    {
+        PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
+    };
 });
 
 builder.Services.AddSignalRSwaggerUi(options =>
 {
     options.RoutePrefix = "signalr-swagger";    // SwaggerUI route (default)
     options.SpecUrl = "/openapi/signalr-v1.json"; // Spec endpoint (default)
     options.DocumentTitle = "SignalR API";       // Browser tab title (default)
+    options.StripAsyncSuffix = true;             // Strip "Async" from display names (default)
 });
 ```
 
@@ -151,6 +160,8 @@ public class AlertNotification : Notification
 ```
 
 > **Note**: `System.Text.Json` polymorphic deserialization requires the type discriminator property to appear **first** in the JSON object. The SwaggerUI plugin handles this automatically for sub-endpoints.
+>
+> By default, `IncludeDiscriminatorInExamples = true` makes the discriminator visible in JSON request examples but hidden in form-urlencoded inputs. Set to `false` to hide the discriminator from all examples (the plugin still injects it at invocation time).
 
 ## Supported Attributes
 

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

@@ -8,90 +8,45 @@
 
 namespace SignalR.OpenApi.Sample.Hubs;
 
-/// <summary>
-/// A sample chat hub demonstrating SignalR.OpenApi features.
-/// </summary>
+/// <inheritdoc cref="IChatHub"/>
 [Tags("Chat")]
-public class ChatHub : Hub<IChatClient>
+public class ChatHub : Hub<IChatClient>, IChatHub
 {
-    /// <summary>
-    /// Sends a message to all connected clients using separate parameters.
-    /// </summary>
-    /// <remarks>
-    /// This demonstrates hub methods with primitive parameters.
-    /// FluentValidation does not apply to primitive parameters — use a request object instead.
-    /// </remarks>
-    /// <param name="user">The name of the sending user.</param>
-    /// <param name="message">The message to send.</param>
-    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    /// <inheritdoc />
     [SignalROpenApiRequestExamples(typeof(SendMessageExamplesProvider))]
-    public async Task SendMessage(string user, string message)
+    public async Task SendMessageAsync(string user, string message)
     {
         await this.Clients.All.ReceiveMessage(user, message);
     }
 
-    /// <summary>
-    /// Sends a direct message using a request object with FluentValidation.
-    /// </summary>
-    /// <remarks>
-    /// This demonstrates hub methods with a single object parameter (flattened schema).
-    /// FluentValidation rules from <see cref="SendMessageRequestValidator"/> are applied to the OpenAPI schema.
-    /// </remarks>
-    /// <param name="request">The message request containing user and message.</param>
-    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    /// <inheritdoc />
     [SignalROpenApiRequestExamples(typeof(SendMessageExamplesProvider))]
-    public async Task SendDirectMessage(SendMessageRequest request)
+    public async Task SendDirectMessageAsync(SendMessageRequest request)
     {
         await this.Clients.All.ReceiveMessage(request.User, request.Message);
     }
 
-    /// <summary>
-    /// Replies to an existing message.
-    /// </summary>
-    /// <remarks>
-    /// This demonstrates hub methods with two object parameters (wrapped schema).
-    /// Each parameter appears as a named property in the request body.
-    /// </remarks>
-    /// <param name="originalMessage">The original message being replied to.</param>
-    /// <param name="reply">The reply message.</param>
-    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    /// <inheritdoc />
     [SignalROpenApiRequestExamples(typeof(ReplyToMessageExamplesProvider))]
-    public async Task ReplyToMessage(ChatMessage originalMessage, ChatMessage reply)
+    public async Task ReplyToMessageAsync(ChatMessage originalMessage, ChatMessage reply)
     {
         await this.Clients.All.ReceiveMessage(reply.User, $"Re: {originalMessage.Message} — {reply.Message}");
     }
 
-    /// <summary>
-    /// Sends a message to a specific group.
-    /// </summary>
-    /// <param name="group">The target group name.</param>
-    /// <param name="user">The name of the sending user.</param>
-    /// <param name="message">The message to send.</param>
-    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
-    public async Task SendToGroup(string group, string user, string message)
+    /// <inheritdoc />
+    public async Task SendToGroupAsync(string group, string user, string message)
     {
         await this.Clients.Group(group).ReceiveMessage(user, message);
     }
 
-    /// <summary>
-    /// Sends a notification to a user. The notification type is polymorphic —
-    /// use the "type" discriminator to select between "text" and "alert".
-    /// </summary>
-    /// <param name="notification">The notification to send (text or alert).</param>
-    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    /// <inheritdoc />
     [SignalROpenApiRequestExamples(typeof(NotificationExamplesProvider))]
-    public async Task SendNotification(Notification notification)
+    public async Task SendNotificationAsync(Notification notification)
     {
         await this.Clients.All.ReceiveMessage(notification.Recipient, $"Notification: {notification.GetType().Name}");
     }
 
-    /// <summary>
-    /// Streams a countdown of numbers.
-    /// </summary>
-    /// <param name="from">The starting number.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>A stream of countdown numbers.</returns>
-    /// <example>10.</example>
+    /// <inheritdoc />
     public async IAsyncEnumerable<int> Countdown(
         int from,
         [EnumeratorCancellation] CancellationToken cancellationToken)

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

@@ -0,0 +1,70 @@
+// Copyright (c) SignalR.OpenApi Contributors. Licensed under the MIT License.
+
+namespace SignalR.OpenApi.Sample.Hubs;
+
+/// <summary>
+/// Defines the server-side methods for the chat hub.
+/// </summary>
+public interface IChatHub
+{
+    /// <summary>
+    /// Sends a message to all connected clients using separate parameters.
+    /// </summary>
+    /// <remarks>
+    /// This demonstrates hub methods with primitive parameters.
+    /// FluentValidation does not apply to primitive parameters — use a request object instead.
+    /// </remarks>
+    /// <param name="user">The name of the sending user.</param>
+    /// <param name="message">The message to send.</param>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    Task SendMessageAsync(string user, string message);
+
+    /// <summary>
+    /// Sends a direct message using a request object with FluentValidation.
+    /// </summary>
+    /// <remarks>
+    /// This demonstrates hub methods with a single object parameter (flattened schema).
+    /// FluentValidation rules from <see cref="SendMessageRequestValidator"/> are applied to the OpenAPI schema.
+    /// </remarks>
+    /// <param name="request">The message request containing user and message.</param>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    Task SendDirectMessageAsync(SendMessageRequest request);
+
+    /// <summary>
+    /// Replies to an existing message.
+    /// </summary>
+    /// <remarks>
+    /// This demonstrates hub methods with two object parameters (wrapped schema).
+    /// Each parameter appears as a named property in the request body.
+    /// </remarks>
+    /// <param name="originalMessage">The original message being replied to.</param>
+    /// <param name="reply">The reply message.</param>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    Task ReplyToMessageAsync(ChatMessage originalMessage, ChatMessage reply);
+
+    /// <summary>
+    /// Sends a message to a specific group.
+    /// </summary>
+    /// <param name="group">The target group name.</param>
+    /// <param name="user">The name of the sending user.</param>
+    /// <param name="message">The message to send.</param>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    Task SendToGroupAsync(string group, string user, string message);
+
+    /// <summary>
+    /// Sends a notification to a user. The notification type is polymorphic —
+    /// use the "type" discriminator to select between "text" and "alert".
+    /// </summary>
+    /// <param name="notification">The notification to send (text or alert).</param>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    Task SendNotificationAsync(Notification notification);
+
+    /// <summary>
+    /// Streams a countdown of numbers.
+    /// </summary>
+    /// <param name="from">The starting number.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A stream of countdown numbers.</returns>
+    /// <example>10.</example>
+    IAsyncEnumerable<int> Countdown(int from, CancellationToken cancellationToken);
+}

samples/SignalR.OpenApi.Sample/Program.cs

@@ -15,9 +15,17 @@
 {
     options.DocumentTitle = "SignalR.OpenApi Sample";
     options.DocumentVersion = "v1";
+    options.IncludeDiscriminatorInExamples = true;
+
+    // Default: camelCase (matches ASP.NET Core default)
+    // For PascalCase:
+    options.JsonSerializerOptions.PropertyNamingPolicy = null;
 });
 builder.Services.AddSignalRFluentValidation();
-builder.Services.AddSignalRSwaggerUi();
+builder.Services.AddSignalRSwaggerUi(options =>
+{
+    options.StripAsyncSuffix = true;
+});
 
 var app = builder.Build();
 

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

@@ -51,6 +51,9 @@ public static IApplicationBuilder UseSignalRSwaggerUi(
             c.ConfigObject.Plugins ??= [];
             c.ConfigObject.Plugins.Add("SignalROpenApiPlugin");
 
+            // Pass SignalR options to the JS plugin via ConfigObject
+            c.ConfigObject.AdditionalItems["signalRStripAsyncSuffix"] = options.StripAsyncSuffix;
+
             // Configure auth UI for JWT Bearer (standard SwaggerUI behavior)
             c.OAuthUsePkce();
         });

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

@@ -517,6 +517,14 @@ var SignalROpenApiPlugin = function (system) {
                 props.operationProps = props.operationProps.set("method", "invoke");
               }
             }
+
+            // Strip "Async" suffix from the display path if configured
+            var configs = system.getConfigs ? system.getConfigs() : {};
+            var stripAsync = configs.signalRStripAsyncSuffix !== false;
+            if (stripAsync && path.match(/Async(\/[^\/]+)?$/)) {
+              var displayPath = path.replace(/Async(\/[^\/]+)?$/, "$1");
+              props.operationProps = props.operationProps.set("path", displayPath);
+            }
           }
 
           return React.createElement(Original, props);

src/SignalR.OpenApi.SwaggerUi/SignalRSwaggerUiOptions.cs

@@ -30,4 +30,11 @@ public class SignalRSwaggerUiOptions
     /// for Windows authentication. Defaults to <see langword="false"/>.
     /// </summary>
     public bool UseDefaultCredentials { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether to strip the "Async" suffix
+    /// from method names in the UI display. The underlying SignalR invocation
+    /// always uses the real method name. Defaults to <see langword="true"/>.
+    /// </summary>
+    public bool StripAsyncSuffix { get; set; } = true;
 }