如何在 OpenAPI / Swagger 规范中定义事件？
How to define events in OpenAPI / Swagger spec?
如何使用 OpenAPI / Swagger specification 定义事件驱动的微服务架构？对于事件，重要的是记录在不同服务之间传递的事件负载，即使它们不是通过 HTTP 路径访问的。
我所看到的一切都是通过 HTTP 路径 API-based 的，所以我现在想用 OpenAPI / Swagger 规范来实现它？
如果您有强类型事件，您可以使用反射来发布事件的结构，这对您的微服务客户端来说应该足够了。
如果您有一些事件描述符（xml 或类似的）用于重新水化事件 store/event 日志中的事件，那么您可以发布这些。
除此之外，我不知道有任何工具可以像 Swagger 一样工作，但用于事件。
我认为您可以在 Swagger 中拥有定义，即使它们没有被任何端点使用。只需在专用部分中声明您需要的任何类型，例如"definitions"。您可以参考您在端点中使用的那些，例如"$ref": "#/definitions/User", as per main Swagger live example.
我希望为它们生成代码，因此您可以针对任何定义编写测试。
如果您使用的是 Java，还有一个替代方案。我从未对此进行过测试，但这个想法可以指导您找到适用于其他平台的解决方案。
您可以使用 "good" 和旧的 Javadoc 以及来自 Enunciate, as explained here:
的 Swagger 模块
You can generate swagger-ui from Javadoc by using Enunciate, which has a Swagger module
这只是一个maven插件。在决赛中，you have 一份 完整的 HTML 服务文档，从您的 JavaDocs..
中删除
OpenAPI 3.1
OpenAPI 规范 3.1 通过顶级 webhooks 属性 支持事件。 OpenAPI 规范 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 到 auto-generate 模式对象，用于 [=65] 等语言=]、Swift、Go 等
OpenAPI 2.0/Swagger 2.0
对于 Swagger 规范 2.0（又名 OpenAPI 规范 2.0），您可以在 alamar 提到的 Swagger 规范中包含定义。 Swagger Codegen 会自动为这些定义创建模型 类，即使它们没有与任何路径关联。我构建并维护了一个 Swagger Spec/Codegen-built SDK in Go for the RingCentral API that has events like this. You can see the auto-generated classes/structs Swagger Codegen builds in the following folder, filtering for the 20 files that end in _event.go. These are currently created using swagger-codegen 2.3.1.
- 生成的文件：https://github.com/grokify/go-ringcentral/tree/master/client
- 代码生成信息：https://github.com/grokify/go-ringcentral/tree/master/codegen
如果您有多个事件类型，拥有一个可以区分您收到的消息类型的事件 属性 可以帮助将其解析为正确的事件 class/struct。在 Go 中，您可以将数据解组两次，一次解组为通用结构以查看事件类型 属性，然后第二次解组实际事件类型。
我还在 Chathooks webhook reformatter project 中维护了示例事件和解析代码的集合，您可以参考。您可以在此处查看示例事件和 (hand-rolled) 语言定义：
- 示例：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 和任何其他基于消息传递的东西一起使用。
如何使用 OpenAPI / Swagger specification 定义事件驱动的微服务架构？对于事件，重要的是记录在不同服务之间传递的事件负载，即使它们不是通过 HTTP 路径访问的。
我所看到的一切都是通过 HTTP 路径 API-based 的，所以我现在想用 OpenAPI / Swagger 规范来实现它？
如果您有强类型事件，您可以使用反射来发布事件的结构，这对您的微服务客户端来说应该足够了。
如果您有一些事件描述符（xml 或类似的）用于重新水化事件 store/event 日志中的事件，那么您可以发布这些。
除此之外，我不知道有任何工具可以像 Swagger 一样工作，但用于事件。
我认为您可以在 Swagger 中拥有定义，即使它们没有被任何端点使用。只需在专用部分中声明您需要的任何类型，例如"definitions"。您可以参考您在端点中使用的那些，例如"$ref": "#/definitions/User", as per main Swagger live example.
我希望为它们生成代码，因此您可以针对任何定义编写测试。
如果您使用的是 Java，还有一个替代方案。我从未对此进行过测试，但这个想法可以指导您找到适用于其他平台的解决方案。
您可以使用 "good" 和旧的 Javadoc 以及来自 Enunciate, as explained here:
的 Swagger 模块You can generate swagger-ui from Javadoc by using Enunciate, which has a Swagger module
这只是一个maven插件。在决赛中，you have 一份 完整的 HTML 服务文档，从您的 JavaDocs..
中删除OpenAPI 3.1
OpenAPI 规范 3.1 通过顶级 webhooks 属性 支持事件。 OpenAPI 规范 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 到 auto-generate 模式对象，用于 [=65] 等语言=]、Swift、Go 等
OpenAPI 2.0/Swagger 2.0
对于 Swagger 规范 2.0（又名 OpenAPI 规范 2.0），您可以在 alamar 提到的 Swagger 规范中包含定义。 Swagger Codegen 会自动为这些定义创建模型 类，即使它们没有与任何路径关联。我构建并维护了一个 Swagger Spec/Codegen-built SDK in Go for the RingCentral API that has events like this. You can see the auto-generated classes/structs Swagger Codegen builds in the following folder, filtering for the 20 files that end in _event.go. These are currently created using swagger-codegen 2.3.1.
- 生成的文件：https://github.com/grokify/go-ringcentral/tree/master/client
- 代码生成信息：https://github.com/grokify/go-ringcentral/tree/master/codegen
如果您有多个事件类型，拥有一个可以区分您收到的消息类型的事件 属性 可以帮助将其解析为正确的事件 class/struct。在 Go 中，您可以将数据解组两次，一次解组为通用结构以查看事件类型 属性，然后第二次解组实际事件类型。
我还在 Chathooks webhook reformatter project 中维护了示例事件和解析代码的集合，您可以参考。您可以在此处查看示例事件和 (hand-rolled) 语言定义：
- 示例：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 和任何其他基于消息传递的东西一起使用。