什么是AsyncAPI？

AsyncAPI 规范是一个机器可读的文档，用于记录和描述事件驱动 API。它不仅是一个规范，而是一个包含了代码生成器、验证器和测试生成器的丰富的生态系统。

AsyncAPI 与 OpenAPI 基于相同的元素进行设计，并共享许多通用构造以简化应用，还提供了一些附加特性以适应事件的需求。它支持各种各样的消息和传输协议(如 AMQP, MQTT, WebSockets, Kafka, JMS, STOMP, HTTP 等)和事件定义格式。因此，API 定义将包含事件有效负载定义、管道名称、应用/传输头、协议和其他用于事件连接、发布和订阅的语义。——Dakshitha Ratnayake

AsyncAPI规范

AsyncAPI规范定义了一组字段，这些字段可用于AsyncAPI文档中描述应用程序的API。该文档可能会引用其他文件以获取其他详细信息或共享字段，但它通常是封装API描述的单个主文档。

此外，AsyncAPI文档在事件驱动系统中充当receivers和senders之间的通信合同。它指定了服务发送消息时所需的有效负载内容，并就消息的属性向接收者提供明确的指导。

asyncapi: 3.0.0info:  title: Cool Example  version: 0.1.0channels:  userSignedUp:    address: user/signedup    messages:      userSignedUp:        description: An event describing that a user just signed up.        payload:          type: object          properties:            fullName:              type: string            email:              type: string              format: email            age:              type: integer              minimum: 18operations:   userSignedUp:    action: send    channel:       $ref: '#/channels/userSignedUp'

事件驱动架构(EDA)

事件驱动架构（EDA）使用事件来触发和服务之间的通信，在使用微服务构建的现代应用程序中很常见。事件是状态更改或更新，例如将购物项目添加到电子商务网站上的购物车中。

1. 客户端订阅API

此时，事件驱动API的客户端向API注册希望接收异步更新的意图，这称为订阅。在订阅时，客户端通常指定API应该向其发布更新事件的接口。

2. 异步事件交付

当后台发生了一些有趣的事情，API以事件的形式异步的将其传递给所有订阅的客户端。

AsyncAPI文档结构

AsyncAPI文档的结构以特定格式定义，必须遵循AsyncAPI规范，主要信息结构如下：

• info/信息字段提供关键的元数据，包括API的标题、版本、描述、联系方式和许可证。该领域提供了API的全面概述，帮助开发人员、架构师和其他利益相关者快速掌握其目的和功能。作为AsyncAPI规范的强制性元素，info字段通常作为用户浏览API文档的初始参考点。
• server/服务器字段允许您详细说明一系列服务器，概述应用程序可以连接的网络端点或消息代理。该领域包括协议、主机、端口和其他选项等重要连接信息，促进了生产、分期或开发等各种环境的连接。
• channels/频道代表了交换消息的通信途径。您可以指定它们的目的、地址和预期的通信消息格式。特定API的消费者可以理解受支持的基于消息的交互和相应的数据模型。
• operations/操作字段用于全面概述应用程序执行的各种操作。它提供了一个清晰、结构化的描述，详细说明应用程序是否发送或接收消息以及每个操作的具体目的。
• components/部件字段允许定义可重用结构或适用于文档各个部分的定义。components中详细描述的项目只有在被此字段外部的属性明确引用时才成为API的一部分。利用它来避免重复，并提高文档的可维护性。

文档结构详细指导参考官方文档。

OpenAPI和AsyncAPI的规范比较

• AsyncAPI与OpenAPI模式兼容。
• AsyncAPI中的消息有效负载可以是任何值，而不仅仅是AsyncAPI/OpenAPI模式。例如，它可能是一个Avro模式。
• AsyncAPI服务器对象与其OpenAPI对象几乎相同，但scheme已重命名为protocol，AsyncAPI引入了一个名为protocolVersion的新属性。AsyncAPI支持多个协议，而不仅仅是HTTP，就像OpenAPI一样。
• OpenAPI路径参数和AsyncAPI通道参数有点不同，因为AsyncAPI没有“查询”和“cookie”的概念，并且可以在消息对象中定义标头参数。因此，AsyncAPI通道参数等价于OpenAPI路径参数。

其它构建事件驱动 API的技术

1、Webhooks：是一个由事件消费者管理的可公开访问的 HTTP POST 接口，事件生产者（比如 API 服务器）可以在事件发生时向 Webhook 发送事件通知。

2、WebSockets：是另一个可以用来构建事件驱动 API 的协议。与 Webhook 不同，WebSocket 协议允许服务器和客户端之间进行持续的双向通信，这意味着双方都可以在需要的时候进行通信以及交换数据。

3、Server-Sent Events(SSE)：是一种与 WebSockets 非常相似的通信协议，但隐含条件是只支持单向数据。SSE 允许基于浏览器的消费者接收从 API 服务器发送的事件通知流。

参考资料

AsyncAPI官方文档
OpenAPI and AsyncAPI
10分钟搞懂事件驱动API
使用AsyncAPI和Springwolf记录Spring事件驱动API