如何生成SignalR接口文档

Question

有没有办法做到这一点？

我用虚张声势为我的其他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

正如评论所建议的，我成功地使用了SigSpec来达到这个目的。

我不得不稍微修修补补，但它确实起到了作用。

Answer 3

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

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

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

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

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

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