Swagger规范定义了一组有限的操作，您可以为模式中的特定路径对象定义这些操作。也就是说，如果你只关心为人类使用记录你的API，你可以自由地走出规范。以WIX文档为例。它使用一个自定义的
我有一个设置，可以使用标准REST获得一些资源，这很容易在swagger中记录下来。当相同的资源发生更改时，会使用websocket将其推送到客户端，因此客户端不必在间隔的基础上进行拉取。
但我怎么能大摇大摆地记录这件事呢？这可能吗？如果没有，您建议使用其他什么工具来记录RESTapi和websocket部分？
OpenAPI 3（又名Swagger 3）对响应格式进行了升级，添加了回调的概念，允许您定义webhook。看看文档的这一部分：响应格式。
在Swagger 2中，我要做的是实现一个API方法，该方法实现的与我期望的回调完全相同，我只是在等待回调的原始方法中引用它。因此，任何消费者至少都可以使用Swagger规范看到我期望他们提供的消息格式。
今天很难找到关于"如何使用异步通信对api进行文档化"的明确答案。它不仅涉及websocket，还涉及服务器发送事件和其他。。。。
如今，对于Rest规范，有许多著名的规范，排名前三的是：-Swagger-RAML-API蓝色打印
它们是关于使用websocket对api进行文档化的方法的许多问题/讨论，。。。
但是Swagger正在社区的帮助下对api规范进行标准化。它被命名为OpenApi。
OpenAPI规范的第3版引入了一种记录webhook/callback的方法。
另一个好的规范是asyncapi.com，它正在深入并尊重可阅读的openApi规范。
HOOK定义来记录其webhook API，并且它不会假装是一个有效的Swagger规范，这可能正是您的情况所需要的。