什么时候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.0

info:

  title: Cool Example

  version: 0.1.0

channels:

  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: 18

operations: 

  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路径参数。