SignalR.OpenApi 1.0.226

SignalR.OpenApi

OpenAPI 3.1 specification generation and SwaggerUI support for ASP.NET Core SignalR hubs.

Features

• Generates OpenAPI 3.1 specifications from SignalR hub methods
• Interactive SwaggerUI with SignalR protocol invocation (no HTTP — real SignalR calls)
• 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.)
• 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
• FluentValidation rules mapped to OpenAPI schema constraints
• Security scheme detection from [Authorize] / [AllowAnonymous]
• JWT Bearer token support in SwaggerUI (header or query string)
• Connection status indicator with automatic reconnection handling
• Form-urlencoded input mode for primitive and flat object parameters
• Multiple named request/response examples via custom attributes
• Embedded @microsoft/signalr bundle (no CDN dependency)
• Zero proprietary attributes required for core functionality

Getting Started

Installation

dotnet add package SignalR.OpenApi
dotnet add package SignalR.OpenApi.SwaggerUi

Usage

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSignalR();
builder.Services.AddSignalROpenApi();
builder.Services.AddSignalRSwaggerUi();

var app = builder.Build();

app.MapHub<ChatHub>("/hubs/chat");
app.MapSignalROpenApi();
app.UseSignalRSwaggerUi();

app.Run();

The OpenAPI specification is served at /openapi/signalr-v1.json. The SwaggerUI is available at /signalr-swagger.

Configuration

builder.Services.AddSignalROpenApi(options =>
{
    options.DocumentTitle = "My SignalR API";
    options.DocumentVersion = "v1";

    // 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)
});

SwaggerUI Features

Method Labels

SignalR operations display custom method labels in SwaggerUI:

Streaming

Streaming operations accumulate items into a growing response array as they arrive. The response shows:

{
  "state": "streaming",
  "count": 5,
  "items": [10, 9, 8, 7, 6]
}

When the stream completes, the state changes to "completed". If an error occurs, it shows "error: ...". A Stop Stream button appears while streaming is active to cancel the subscription.

Client Events

Client events (from Hub<TClient> interface methods) appear as EVENT operations. When you expand one, an event log panel shows:

• Connection status: Connected / Disconnected indicator
• Connect & Listen: Button to establish hub connection and start receiving events
• Event log: Real-time list of received events with timestamps and JSON payloads
• Clear Log: Button to reset the event history

Events are automatically subscribed when connecting to a hub via any invoke or stream operation.

Request Body Input Modes

Hub methods with parameters support two input modes, selectable via a content-type dropdown in SwaggerUI:

The dropdown appears above the request body when you click Try it out. Form field values are automatically coerced to the correct type (e.g., "5" → 5 for integers, "true" → true for booleans).

Note: Methods with multi-object parameters (two or more complex objects) only support application/json because SwaggerUI cannot render nested objects as form fields.

Polymorphic Parameters

Parameters using [JsonPolymorphic] / [JsonDerivedType] are supported via two mechanisms:

1. Main endpoint (/hubs/Chat/SendNotification) — uses oneOf with a discriminator for the type selector dropdown in JSON mode.
2. OData-style sub-endpoints (/hubs/Chat/SendNotification/text, /hubs/Chat/SendNotification/alert) — each derived type gets its own endpoint with a flat schema, supporting both JSON and form-urlencoded input.

[JsonPolymorphic(TypeDiscriminatorPropertyName = "type")]
[JsonDerivedType(typeof(TextNotification), "text")]
[JsonDerivedType(typeof(AlertNotification), "alert")]
public abstract class Notification
{
    public required string Recipient { get; set; }
}

public class TextNotification : Notification
{
    public required string Content { get; set; }
}

public class AlertNotification : Notification
{
    public required string Title { get; set; }
    public required string Severity { get; set; }
}

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

Request Body Schema

Hub method parameters are mapped to the OpenAPI request body schema:

• Single complex object parameter (e.g., SendMessage(SendMessageRequest request)): The object's properties are flattened directly into the request body — no wrapper property.
• Multiple parameters (e.g., SendMessage(string user, string message) or Reply(ChatMessage original, ChatMessage reply)): Each parameter becomes a named property in a wrapper object.
• Primitive parameters (e.g., string, int): Always wrapped with the parameter name as the property key.

Response Codes

• 204 No Content: Hub methods returning void or Task (no return value)
• 200 OK: Hub methods returning Task<T> or streaming results

Examples

Provide multiple named examples for request and response bodies using custom attributes and the ISignalROpenApiExamplesProvider<T> interface.

1. Define a request model and example provider

public class SendMessageRequest
{
    public string User { get; set; } = string.Empty;
    public string Message { get; set; } = string.Empty;
}

public class SendMessageExamplesProvider : ISignalROpenApiExamplesProvider<SendMessageRequest>
{
    public IEnumerable<SignalROpenApiExample<SendMessageRequest>> GetExamples()
    {
        yield return new SignalROpenApiExample<SendMessageRequest>(
            "Greeting",
            new SendMessageRequest { User = "Alice", Message = "Hello, everyone!" })
        {
            Summary = "A friendly greeting",
        };

        yield return new SignalROpenApiExample<SendMessageRequest>(
            "Question",
            new SendMessageRequest { User = "Bob", Message = "What time is the meeting?" })
        {
            Summary = "Asking a question",
        };
    }
}

2. Apply the attribute to a hub method

[SignalROpenApiRequestExamples(typeof(SendMessageExamplesProvider))]
public async Task SendMessage(string user, string message)
{
    await Clients.All.ReceiveMessage(user, message);
}

The examples appear in SwaggerUI's example dropdown for the request body. Response examples work the same way using [SignalROpenApiResponseExamples].

Example providers are resolved from DI first, with Activator.CreateInstance as a fallback.

FluentValidation Integration

The SignalR.OpenApi.FluentValidation package automatically maps FluentValidation rules to OpenAPI schema constraints.

Note: FluentValidation applies to complex object parameters only (classes with properties). Hub methods with primitive parameters (e.g., string user, string message) are not validated — use a request object instead (e.g., SendMessage(SendMessageRequest request)). When a hub method has a single complex object parameter, the schema is flattened — the object's properties appear directly in the request body without a wrapper property.

Setup

builder.Services.AddValidatorsFromAssemblyContaining<MyValidator>();
builder.Services.AddSignalROpenApi();
builder.Services.AddSignalRFluentValidation();

Supported Rules

Validators are resolved from DI via IValidator<T>. Nested child validators are supported.

Packages

Related Projects

The following open-source projects also provide OpenAPI, SwaggerUI, or developer tooling for ASP.NET Core SignalR hubs. SignalR.OpenApi was designed with awareness of these projects and aims to combine the best aspects of each.

Other related projects

License

MIT