How do I generate API documentation for SignalR

Question

Is there a way to do this?

I have swashbuckle generating content for my other APIs but I don't believe it works for SignalR.

Answer 1

Here's a Nuget package which can help you.

Nuget link: https://www.nuget.org/packages/SignalRSwaggerGen/

Github link: https://github.com/essencebit/SignalRSwaggerGen/wiki

First you need to decorate your SignalR hubs with attributes from SignalRSwaggerGen.Attributes namespace:

[SignalRHub]
public class SomeHub : Hub
{
}

Then you add SignalRSwaggerGen to Swagger generator:

services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "Some API v1", Version = "v1" });
    // here some other configurations maybe...
    options.AddSignalRSwaggerGen();
});

For more information please refer to Github documentation.

Answer 2

I successfully used SigSpec for this purpose as suggested by the comment.

I had to tinker a little but it did the job.

Answer 3

I search a lot and I found this Nuget package SignalRSwaggerGen but the documentation is misleading and not clear as you thought but it's a great package for documenting Hubs for SignalR in Swagger and will provide here snippets I hope they add a clear documentation.

• Put the data annotation that says that's a SignalR Hub just for Swagger.

    /// <summary>
    /// Authorized Presence Hub that's accessed via 'hubs/presence'.
    /// </summary>
    [SignalRHub]
    [Authorize]
    public sealed class PresenceHub : Hub {}
  

• Put the data annotation that says the name of the method that you will use the name for the method to be used.

    /// <summary>
    /// UserIsOnline Hub method method that's used for tracking the online users.
    /// <returns>Returns the full name with any user that's just got online.</returns>
    /// </summary>
    [SignalRMethod("UserIsOnline")]
    public override async Task OnConnectedAsync()
    {
        await Clients.Others.SendAsync("UserIsOnline", Context.User.GetUserFullName());
    }
  

• to make the XML documenation take effect you have to put this in Swagger.

    builder.Services.AddSwaggerGen(opts =>
    {
        var xmlCommentsFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlCommentsFullPath = Path.Combine(AppContext.BaseDirectory, xmlCommentsFile);
  
        opts.IncludeXmlComments(xmlCommentsFullPath);
  
        opts.AddSignalRSwaggerGen(_ =>
        {
            _.UseHubXmlCommentsSummaryAsTagDescription =  true;
            _.UseHubXmlCommentsSummaryAsTag = true;
            _.UseXmlComments(xmlCommentsFullPath);
        });
    });
  

and make sure to add <GenerateDocumentationFile>true<GenerateDocumentationFile> as the following:-

    <PropertyGroup>
        <TargetFramework>net7.0</TargetFramework>
        <GenerateDocumentationFile>true</GenerateDocumentationFile>
        <NoWarn>$(NoWarn);1591</NoWarn>
    </PropertyGroup>

Answer 4

Assuming that you're using Asp.NET Core, custom documentation can be injected at startup time.

In your Startup.ConfigureServices you should already have a Swagger section:

services.AddSwaggerGen(c =>
{
    ...
})

Just add a custom XML file to Swagger documentation:

services.AddSwaggerGen(c =>
{
    c.IncludeXmlComments("custom_doc.xml");
})

where custom_doc.xml is a standard C# XML documentation file.