events - 如何在 OpenAPI/Swagger 规范中定义事件？

Question

关闭。这个问题不符合Stack Overflow guidelines .它目前不接受答案。












想改进这个问题？将问题更新为 on-topic对于堆栈溢出。

4年前关闭。




Improve this question




如何使用 OpenAPI / Swagger specification 定义事件驱动的微服务架构？ ?对于事件，重要的是记录在不同服务之间传递的事件有效负载，即使它们不是通过 HTTP 路径访问的。
我所看到的一切都是通过 HTTP 路径基于 API 的，所以我现在想知道用 OpenAPI/Swagger 规范来实现它吗？

Answer 1

开放API 3.1
OpenAPI Spec 3.1 通过顶级 webhooks 支持事件属性(property)。 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 将自动为这些定义创建模型类，即使它们没有与任何路径关联。我构建并维护了一个 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

代码生成信息: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

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