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

Question

如何使用OpenAPI / Swagger规范定义基于事件驱动的微服务架构？对于事件，重要的是记录在不通过HTTP路径访问时传递给不同服务的事件负载。我见过的所有内容都是基于API的HTTP路径，因此我想知道如何使用OpenAPI / Swagger规范实现这一点？

- Hammer

---

另一种可能的选择是在负载中使用模式属性或链接到模式。 - Frank Fajardo

另一个例子说明管理员如何破坏社区。任何时候都没有要求书籍/工具/库。这是一个有效的问题，但出于某种原因，管理员会通过行使权威感到兴奋。 - stoic

Answer 1

OpenAPI 3.1

OpenAPI规范3.1通过顶级webhooks属性支持事件。详细定义请看OpenAPI规范3.1：

• 规范定义：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规范2.0（又称为OpenAPI规范2.0），您可以像alamar提到的那样在Swagger规范中包含定义。即使这些定义与任何路径都没有关联，Swagger Codegen也会自动创建模型类。我构建和维护了一个使用Swagger Spec/Codegen构建的RingCentral API的Go SDK，其中包含此类事件。您可以在下面的文件夹中查看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

AsyncAPI

与OpenAPI的替代方案是使用AsyncAPI，它是一种面向事件驱动架构的规范。它是协议不可知的，因此可以与基于消息的Kafka、Websocket、MQTT、AMQP和其他任何东西一起使用。

- Grokify

Answer 2

我认为即使在Swagger中没有被任何端点使用，你也可以定义它们。只需在专门的部分（例如“definitions”）中声明所需的任何类型。您可以像以下方式引用端点中正在使用的内容："$ref": "#/definitions/User"，就像主Swagger示例一样。

我预计将针对其生成代码，因此您可以编写针对任何定义的测试。

- alamar

Answer 3

如果您有强类型事件，您可以使用反射来发布事件的结构，这对于您的微服务的客户端应该足够了。

如果您有一些事件描述符（XML或类似的）用于从事件存储/事件日志中重新生成事件，则可以发布这些描述符。

否则，我不知道是否有任何类似Swagger但用于事件的工具。

- Constantin Galbenu

Answer 4

如果您正在使用Java，那么还有一种替代方案。我从未尝试过这个方法，但这个想法可以指导您解决其他平台的问题。

您可以使用“好”的老Javadoc，以及来自Enunciate的Swagger模块，如此处所述:

您可以通过使用具有Swagger模块的Enunciate从Javadoc生成swagger-ui

这只是一个Maven插件。最终，您将拥有一个从JavaDocs中获取的服务的完整HTML文档。

- Dherik