AsyncAPI definition among multiple yaml files

Question

I am new using AsyncAPI specification. I have defined an AsyncAPI definition in a YAML file. As the definition is growing up I wanted to split it among several files. But I have no idea about how to do this.

I have search some examples on Google, but any decent result was found. Could anyone show me some examples about this topic? Or guide me to do this.

Thanks in advance.

Answer 1

The short answer is, by using the Reference Object($ref) where possible, so make sure to check the AsyncAPI specification to figure out where references can be used.

That way you can use relative references to achieve splitting up the AsyncAPI document into multiple files:

##### ./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:
  ...

If you employ ownership of messages (say application A owns a message application B consumes) you could reference them as such:

##### ./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"

We currently have some discussions around what ways you can define an AsyncAPI document and how reusability plays a role (with different examples) - https://github.com/asyncapi/spec/issues/628#issuecomment-968050476

Tools

When you split up your AsyncAPI document, you might want to have some tools help you out to easier work with them.

Many of the tools are still WIP, but important they get tried and adapted to real use-cases. So I want to encourage using them and report back what you find!

Bundler

Now that you have started with reusability, you might encounter use-cases where you want to bundle things back together. That is where the AsyncAPI Bundler comes into play.

Optimizer

If you already have AsyncAPI documents that you wish to split up into more reusable chunks, you can use the AsyncAPI optimizer to help you in that effort.