AsyncAPI Bundler

[Souvikns]

AsyncAPI Bundler

repo: https://github.com/Souvikns/asyncapi-bundler

Introduction

With AsyncAPI Bundler combine multiple specification files into one. It also resolves external $refs so you can also use it to bundle all references from a single AsyncAPI document into a single file as talked here.

Usage Example

I would like to demonstrate two different ways to use AsyncAPI Bundler.

1. Combine multiple complete AsyncAPI specifications into one document.

This use case was inspired by Zorabots, zbos-mqtt-api where they have multiple AsyncAPI documents for each interface which is easy to maintain and develop, but customers do not want to see the complexity of the system as it is adding noise. Customers want to see the system as on big API. This is what the AsyncAPI Bundler aims to solve by providing a way to merge multiple AsyncAPI documents.

Some things to consider

• All AsyncAPI documents should be valid and complete which means that any parser should validate each document.
• As each document is a part of the complete system, no two documents should define the same channel or schema property.

Example

CLI Command

asyncapi-bundle ./camera.yml ./audio.yml -b ./base.yml -o ./all.yml

Files

#audio.yml
asyncapi: 2.0.0
id: 'urn:zbos-mqtt-api'
defaultContentType: application/json
info:
  title: Audio
  version: 2.6.3
  description: API for communication with ZBOS by Zora Robotics.
  contact:
    email: [email protected]
channels:
  zbos/audio/player/start:
    publish:
      summary: Play media
      description: |
        Play specific media from audio options
      tags:
        - name: Audio
          description: All audio related topics.
      message:
        payload:
          type: object
          properties:
            requestId:
              type: string
            url:
              type: string
            loop:
              type: boolean
        name: AudioOptions
        examples:
          - payload:
              requestId: '1'
              url: Url
              loop: true
  zbos/audio/player/stop:
    publish:
      summary: Stop media
      description: ''
      tags:
        - name: Audio
          description: All audio related topics.
      message:
        $ref: '#/components/messages/emptyMessage'
components:
  messages:
    emptyMessage:
      payload:
        type: object
      name: EmptyMessage
      summary: Empty message


# camera.yml
asyncapi: 2.0.0
id: 'urn:zbos-mqtt-api'
defaultContentType: application/json
info:
  title: Camera
  version: 2.6.3
  description: API for communication with ZBOS by Zora Robotics.
  contact:
    email: [email protected]
channels:
  zbos/camera/picture/event:
    subscribe:
      summary: 'event: Get picture'
      description: ''
      tags:
        - name: Camera
          description: All camera related topics.
      message:
        payload:
          type: string
        name: String
  zbos/camera/picture/get:
    publish:
      summary: Get picture
      description: ''
      tags:
        - name: Camera
          description: All camera related topics.
      message:
        $ref: '#/components/messages/keyMessage'
components:
  messages:
    keyMessage:
      payload:
        type: object
        properties:
          key:
            type: string
            description: Required random key
      name: KeyResult
      summary: Random key
      examples:
        - payload:
            key: ABCxyz

# base.yml
asyncapi: 2.0.0
id: 'urn:zbos-mqtt-api'
defaultContentType: 'application/json'
info:
  title: ZBOS MQTT API
  version: 2.6.3
  description: API for communication with ZBOS by Zora Robotics.
  contact:
    email: [email protected]
servers:
  local:
    url: '127.0.0.1'
    protocol: mqtt
    description: This is the local robot broker.
    variables:
      port:
        enum:
          - '1883'
          - '9001'
        default: '1883'
  cloud:
    url: zbos-mqtt.zoracloud.com
    protocol: mqtt
    description: This is the cloud broker.
    variables:
      port:
        enum:
          - '1883'
          - '1884'
          - '9001'
          - '9002'

# all.yml
asyncapi: 2.0.0
id: urn:zbos-mqtt-api
defaultContentType: application/json
info:
  title: ZBOS MQTT API
  version: 2.6.3
  description: API for communication with ZBOS by Zora Robotics.
  contact:
    email: [email protected]
channels:
  zbos/audio/player/start:
    publish:
      summary: Play media
      description: |
        Play specific media from audio options
      tags:
        - name: Audio
          description: All audio related topics.
      message:
        payload:
          type: object
          properties:
            requestId:
              type: string
            url:
              type: string
            loop:
              type: boolean
        name: AudioOptions
        examples:
          - payload:
              requestId: "1"
              url: Url
              loop: true
  zbos/audio/player/stop:
    publish:
      summary: Stop media
      description: ""
      tags:
        - name: Audio
          description: All audio related topics.
      message:
        $ref: "#/components/messages/emptyMessage"
  zbos/camera/picture/event:
    subscribe:
      summary: "event: Get picture"
      description: ""
      tags:
        - name: Camera
          description: All camera related topics.
      message:
        payload:
          type: string
        name: String
  zbos/camera/picture/get:
    publish:
      summary: Get picture
      description: ""
      tags:
        - name: Camera
          description: All camera related topics.
      message:
        $ref: "#/components/messages/keyMessage"
components:
  messages:
    emptyMessage:
      payload:
        type: object
      name: EmptyMessage
      summary: Empty message
    keyMessage:
      payload:
        type: object
        properties:
          key:
            type: string
            description: Required random key
      name: KeyResult
      summary: Random key
      examples:
        - payload:
            key: ABCxyz
servers:
  local:
    url: 127.0.0.1
    protocol: mqtt
    description: This is the local robot broker.
    variables:
      port:
        enum:
          - "1883"
          - "9001"
        default: "1883"
  cloud:
    url: zbos-mqtt.zoracloud.com
    protocol: mqtt
    description: This is the cloud broker.
    variables:
      port:
        enum:
          - "1883"
          - "1884"
          - "9001"
          - "9002"

2. Bundle all references from a single AsyncAPI document into a single file.

From the above example, each individual AsyncAPI document could in turn depend on external reference which needs to be resolved before merging. Inspired by @magicmatatjahu idea we can solve both use cases simultaneously.

Some things to consider

• Here we work with only one AsyncAPI specification.
• $ref pointing to other external files might not be complete.

Example

CLI Command

asyncapi-bundle ./asyncapi.yaml -o all.yaml

Files

# asyncapi.yaml
asyncapi: '2.2.0'
info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signups
channels:
  user/signedup:
    subscribe:
      message:
        $ref: './messages.yaml#/messages/UserSignedUp'

# messages.yaml
messages:
  UserSignedUp:
    payload:
      type: object
      properties:
        displayName:
          type: string
          description: Name of the user
        email:
          type: string
          format: email
          description: Email of the user

# all.yaml
asyncapi: 2.2.0
info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signups
channels:
  user/signedup:
    subscribe:
      message:
        payload:
          type: object
          properties:
            displayName:
              type: string
              description: Name of the user
            email:
              type: string
              format: email
              description: Email of the user

Future of the Project

If the project is liked and it serves any purpose, I would like to donate the project to AsyncAPI Initiative or port the logic to parser-js to further develop and maintain the project.

Next Feature that I would work on

• Right now all the external references are merged in the schema instead of merging the data in the components and updating the refs as suggested here.
• Circular ref is not supported, which needs to be addressed next.

Thanks to -

• @derberg
• @magicmatatjahu

[boyney123]

Can't wait for this, going to be great!