如何为 SignalR 生成 API 文档答案

【问题标题】：How do I generate API documentation for SignalR如何为 SignalR 生成 API 文档
【发布时间】：2015-05-10 23:50:45
【问题描述】：

有没有办法做到这一点？

我已经为我的其他 API 生成内容，但我认为它不适用于 SignalR。

【问题讨论】：

我对这里的同一件事非常感兴趣，尽管我越来越认为 SignalR 主要用于内部通信，即；第一方之间。将其与调用 SignalR 的动态特性结合起来，我认为没有像 Swashbuckle 这样可靠的工具可用。我将尝试使用我发现的生成 TypeScript 接口但尚未建立工作流的库。
另外，如果你想公开一个公共的“实时”API，也许回调方案更适合。 Facebook 或 Github 之类的东西，但这对于简单的网页项目并没有真正的帮助。
我找不到任何工具来为 SignalR 生成 swagger 文档，但我希望有人能指出我错过的东西。我很惊讶这个问题甚至没有尝试回答。
我的意思是，您可以只使用 JSDoc cmets 并使用任何一种旨在从中创建文档的工具。比如TypeDoc.
我在这里创建了一个原型 SignalR 生成器：github.com/RSuter/SigSpec

标签： c# signalr swashbuckle code-documentation

【解决方案1】：

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

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

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

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

[SignalRHub]
public class SomeHub : Hub
{
}

然后将 SignalRSwaggerGen 添加到 Swagger 生成器：

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

更多信息请参考 Github 文档。

【讨论】：

最新版本的包带来了自动发现选项，这样你就不需要用属性来装饰方法和它们的参数，这样可以减少代码的噪音。还支持多个 Swagger 文档和其他简洁的东西。
感谢这个包。从 Wiki 中我不清楚是否不再需要装饰方法及其参数。也许我错过了一些东西，但如果是这样，你能相应地更新 Wiki 吗？
@ruzgarustu ，更新了 Wiki。很抱歉让您感到困惑，感谢您的反馈！

【解决方案2】：

按照评论的建议，我成功地将SigSpec 用于此目的。

我不得不稍微修改一下，但它完成了工作。

【讨论】：

您好，很遗憾，我无法再访问该项目的源代码。我记得 ui 中的情况并不正确（至少在我们拥有的版本中），但我们设法将生成的 json 集成到 UI 中，就像其他控制器一样。我们的目的是以某种方式记录集线器，而那个技巧（使它看起来像一个控制器）和其他一些技巧可以完成这项工作。（我知道这不是答案，可能没有帮助）

【解决方案3】：

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

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

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

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

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

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

【讨论】：

您是在回答关于 signalR - web socket 协议工具 api 文档还是关于休息？
Swagger 不支持 SignalR，因为 OpenAPI 不支持 RPC API。见