如何使用Swagger规范进行事件？

Question

所述扬鞭/ OpenAPI的规范是对文件有用和运行针对HTTP的API自动化测试.但是,我运行事件驱动的微服务架构,记录在不同服务之间传递的事件有效负载非常重要,即使它们不是通过HTTP路径访问也是如此.由于我所看到的一切都是基于API的HTTP路径,我想知道Swagger如何处理这个问题？

Answer 1

开放API 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

开放API 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 将自动为这些定义创建模型类，即使它们不与任何路径相关联。我在 Go 中为具有此类事件的 RingCentral API构建并维护了 Swagger Spec/Codegen 构建的SDK。您可以在以下文件夹中看到自动生成的类/结构 Swagger Codegen 构建，过滤以_event.go. 这些当前是使用swagger-codegen2.3.1创建的。

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

如果您有多种事件类型，拥有一个可以区分您正在接收的消息类型的事件属性可以帮助将其解析为正确的事件类/结构。在 Go 中，您可以将数据解组两次，一次进入通用结构以查看事件类型属性，然后第二次查看实际事件类型。

我还在Chathooks webhook 重新格式化项目中维护了一组示例事件和解析代码，您可以参考。您可以在此处查看示例事件和（手工制作的）语言定义：

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

异步API

另一种方法是使用AsyncAPI是事件驱动架构的规范。它与协议无关，因此可以与 Kafka、Websocket、MQTT、AMQP 和任何其他基于消息传递的东西一起使用。