OpenAPI 3.1

OpenAPI Spec 3.1通过顶级webhooks属性支持事件。OpenAPI Spec 3.1在这里定义了webhook支持：

• 质量标准定义：https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md
• 规范示例：https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.1/webhook-example.yaml

OpenAPI 3.0

对于处理OAS 3.0的工具，仅使用模式定义事件体仍然很有用，因为这样的定义可以被像OpenAPI Generator这样的代码生成工具用来为Java、Swift、Go等语言自动生成模式对象。

OpenAPI 2.0 / Swagger 2.0

对于Swagger Spec 2.0（又名OpenAPI Spec 2.0），您可以在Alamar提到的Swagger规范中包含定义。Swagger Codegen将自动为这些定义创建模型类，即使它们没有与任何路径相关联。我构建并维护了一个Swagger Spec/Codegen构建的SDK in Go for the RingCentral API，它包含这样的事件。您可以在以下文件夹中看到自动生成的类/结构Swagger Codegen构建，过滤以_event.go结尾的20个文件。目前使用的是swagger-codegen 2.3.1。

• 生成的文件：https://github.com/grokify/go-ringcentral/tree/master/client
• Codegen信息：https://github.com/grokify/go-ringcentral/tree/master/codegen

如果您有多个事件类型，则具有可以区分您正在接收的消息类型的事件属性可以帮助将其解析为正确的事件类/结构。在Go语言中，你可以对数据进行两次解组，一次是将数据解组到一个泛型结构体中以查看事件类型属性，第二次是对实际的事件类型进行解组。
我还在Chathooks webhook reformatter project中维护了一组示例事件和解析代码，您可以使用它们作为参考。您可以在这里看到示例事件和（手动）语言定义：

• 示例：https://github.com/grokify/chathooks/tree/master/docs/handlers
• 定义：https://github.com/grokify/chathooks/tree/master/src/handlers

AsyncAPI

OpenAPI的一个替代方案是使用AsyncAPI，这是一个事件驱动架构的规范。它与协议无关，因此可以与Kafka，WebSocket，MQTT，AMQP和其他任何基于消息传递的东西一起使用。

我认为你可以在Swagger中有定义，即使它们没有被任何端点使用。只需在专用部分中声明您需要的任何类型，例如。“定义”。您可以引用您在端点中使用的那些，例如。"$ref": "#/definitions/User"、as per main Swagger live example。
我希望为它们生成代码，这样您就可以针对任何定义编写测试。

如果你有强类型的事件，你可以使用反射来发布事件的结构，这对你的微服务的客户端来说应该足够了。
如果你有一些事件描述符（xml或类似的）用于从事件存储/事件日志中重新合成事件，那么你可以发布它们。
除此之外，我不知道有什么工具可以像Swagger一样工作，但它是针对事件的。

如果你使用的是Java，还有一个替代方案。我从来没有测试过这个，但这个想法可以指导您为其他平台提供解决方案。
您可以使用“好”和旧的Javadoc以及来自Enunciate的Swagger模块，如here所解释的：
可以使用Enunciate从Javadoc生成swagger-ui，Enunciate有一个Swagger模块
它只是一个maven插件。最后，you have a * 从JavaDocs.* 中抓取的服务的完整HTML文档。