多个yaml文件的AsyncAPI定义

Question

我是新使用AsyncAPI规范的。我在YAML文件中定义了一个AsyncAPI定义。随着定义的发展，我想把它分成几个文件。但我不知道该怎么做。

我在Google上搜索了一些例子，但是找到了一个不错的结果。有人能给我举一些关于这个话题的例子吗？或者引导我这样做。

提前谢谢。

Answer 1

简单的回答是，在可能的情况下使用参考对象($ref)，所以一定要检查AsyncAPI规范，找出可以在哪里使用引用。

通过这种方式，您可以使用相对引用来实现将AsyncAPI文档拆分为多个文件：

##### ./asyncapi.yaml
asyncapi: 2.3.0
...
channels:
  user/signedup:
    subscribe:
      message:
       $ref: "./messages/userSignedUp.yaml"

##### ./messages/userSignedUp.yaml
name: UserSignup
title: User signup
summary: Action to sign a user up.
description: A longer description
contentType: application/json
payload:
  ...

如果您使用消息的所有权(例如，应用程序A拥有消息应用程序B消耗的消息)，您可以这样引用它们：

##### ./asyncapi.A.yaml
asyncapi: 2.3.0
...
channels:
  user/signedup:
    subscribe:
      message:
        $ref: "#/components/messages/userSignedUp"
components: 
  messages: 
    UserSignup:
      name: UserSignup
      title: User signup
      summary: Action to sign a user up.
      description: A longer description
      contentType: application/json
      payload:
        ...
##### ./asyncapi.B.yaml
...
channels:
  user/signedup:
    publish:
      message:
        $ref: "./asyncapi.A.yaml#/components/messages/userSignedUp"

我们目前正在讨论如何定义AsyncAPI文档，以及可重用性如何发挥作用(通过不同的示例)- https://github.com/asyncapi/spec/issues/628#issuecomment-968050476。

工具

当您拆分您的AsyncAPI文档时，您可能希望有一些工具帮助您更容易地使用它们。

许多工具仍然是WIP，但重要的是要尝试并适应实际的用例。因此，我想鼓励使用他们，并报告你的发现！

邦德勒

既然您已经开始使用可重用性，那么您可能会遇到一些用例，您希望将它们打包回一起。这就是AsyncAPI邦德勒发挥作用的地方。

优化器

如果您已经有了希望拆分成更多可重用块的AsyncAPI文档，则可以使用AsyncAPI优化器来帮助您完成这一任务。