如何为SignalR生成API文档

Question

有没有办法做到这一点？

我有swashbuckle为我的其他API生成内容但我不相信它适用于SignalR.

Answer 1

这是一个可以帮助您的 Nuget 包。

Nuget 链接：https ://www.nuget.org/packages/SignalRSwaggerGen/

Github 链接：https : //github.com/Dorin-Mocan/SignalRSwaggerGen/wiki

首先，您需要使用 SignalRSwaggerGen.Attributes 命名空间中的属性装饰您的 SignalR 集线器：

[SignalRHub(path: "/hubs/SomeHub")]
public class SomeHub : Hub
{
    [SignalRMethod(name: "nameOfTheMethodCalledOnTheClientSide", operationType: OperationType.Put)] 
    public async Task SomeMethod([SignalRArg] int arg1, [SignalRArg] object arg2, CancellationToken cancellationToken = default)
    {
        if (Clients == null) return;
        await Clients.All.SendAsync("nameOfTheMethodCalledOnTheClientSide", arg1, arg2, cancellationToken);
    }
}

然后添加 SignalRSwaggerGen.SignalRSwaggerGen 类作为 Swagger 生成器的文档过滤器：

services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "Some API v1", Version = "v1" });
    // here some other configurations maybe...
    options.DocumentFilter<SignalRSwaggerGen.SignalRSwaggerGen>(new List<Assembly> { typeof(SomeHub).Assembly, typeof(SomeHubFromAnotherAssembly).Assembly });
});

更多信息请参考 Github 文档。

Answer 2

假设您使用的是 Asp.NET Core，则可以在启动时注入自定义文档。

在你的中Startup.ConfigureServices你应该已经有一个 Swagger 部分：

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

只需将自定义 XML 文件添加到 Swagger 文档即可：

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

其中custom_doc.xml是标准 C# XML 文档文件。