Skip to content

asyncapi/bundler

AsyncAPI Bundler

Github license PR testing - if Node project npm

Overview

An official library that lets you bundle/merge your specification files into one. AsyncAPI Bundler can help you if:

your specification file is divided into different smaller files and is using JSON `$ref` property to reference components
# asyncapi.yaml
asyncapi: '2.4.0'
info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signups
channels:
  user/signup:
    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

# After combining
asyncapi: 2.4.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
you have different standalone specification files that define a larger system, see examples here
# signup.yaml
asyncapi: '2.4.0'
info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user Signup

channels:
  user/signedup:
    subscribe:
      message:
        payload:
          type: object
          properties:
            displayName:
              type: string
            email:
              type: string
              format: email


# login.yaml
asyncapi: '2.4.0'
info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signup

channels:
  user/loggenin:
    subscribe:
      message:
        payload:
          type: object
          properties:
            displayName:
              type: string

# After combining
# asyncapi.yaml
asyncapi: '2.4.0'
info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge for processing user authentication

channles:
  user/signedup:
    subscribe:
      message:
        payload:
          type: object
          properties:
            displayName:
              type: string
            email:
              type: string
              format: email
  user/loggedin:
    subscribe:
      message:
        payload:
          type: object
          properties:
            displayName:
              type: string

Installation

npm install @asyncapi/bundler

Usage

AsyncAPI Bundler can be easily used within your JavaScript projects as a Node.js module:

'use strict';

const { readFileSync, writeFileSync } = require('fs');
const bundle = require('@asyncapi/bundler');

async function main() {
  const filePaths = ['./camera.yml','./audio.yml'];
  const document = await bundle(
    filePaths.map(filePath => readFileSync(filePath, 'utf-8')), {
      base: readFileSync('./base.yml', 'utf-8'),
    }
  );

  console.log(document.yml()); // the complete bundled AsyncAPI document
  writeFileSync('asyncapi.yaml', document.yml()); // the complete bundled AsyncAPI document
}

main().catch(e => console.error(e));

Resolving external references into components

You can resolve external references by moving them to Messages Object, under components/messages.

For example
# main.yaml
asyncapi: 2.5.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'
  test:
    subscribe:
      message:
        $ref: '#/components/messages/TestMessage'
components:
  messages:
    TestMessage:
      payload:
        type: string

# 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
  UserLoggedIn:
    payload:
      type: object
      properties:
        id: string

# After combining
# asyncapi.yaml
asyncapi: 2.5.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: '#/components/messages/UserSignedUp'
  test:
    subscribe:
      message:
        $ref: '#/components/messages/TestMessage'
components:
  messages:
    TestMessage:
      payload:
        type: string
    UserSignedUp:
      payload:
        type: object
        properties:
          displayName:
            type: string
            description: Name of the user
          email:
            type: string
            format: email
            description: Email of the user

TypeScript

import { readFileSync, writeFileSync } from 'fs';
import bundle from '@asyncapi/bundler';

async function main() {
  const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
    referenceIntoComponents: true,
  });

  console.log(document.yml()); // the complete bundled AsyncAPI document
  writeFileSync('asyncapi.yaml', document.yml());  // the complete bundled AsyncAPI document
}

main().catch(e => console.error(e));

JavaScript CJS module system

'use strict';

const { readFileSync, writeFileSync } = require('fs');
const bundle = require('@asyncapi/bundler');

async function main() {
  const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
    referenceIntoComponents: true,
  });
  writeFileSync('asyncapi.yaml', document.yml());
}

main().catch(e => console.error(e));

JavaScript ESM module system

'use strict';

import { readFileSync, writeFileSync } from 'fs';
import bundle from '@asyncapi/bundler';

async function main() {
  const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
    referenceIntoComponents: true,
  });
  writeFileSync('asyncapi.yaml', document.yml());
}

main().catch(e => console.error(e)); 

bundle(files, [options])

Kind: global function

Param Type Description
files Array.<string> Array of stringified AsyncAPI documents in YAML format, that are to be bundled (or array of filepaths, resolved and passed via Array.map() and fs.readFileSync, which is the same).
[options] Object
[options.base] string | object Base object whose properties will be retained.
[options.referenceIntoComponents] boolean Pass true to resolve external references to components.

Contributors

Thanks goes to these wonderful people (emoji key):

souvik
souvik

πŸ’» πŸ€” 🎨 πŸ‘€ 🚧 πŸ“–
Maciej UrbaΕ„czyk
Maciej UrbaΕ„czyk

πŸ€” πŸ‘€
Mohd Toukir Khan
Mohd Toukir Khan

πŸš‡
MrYugs
MrYugs

πŸ“–
Amanpreet Singh Bedi
Amanpreet Singh Bedi

πŸ“–
Alexey Vasilevich
Alexey Vasilevich

πŸ“–
Viacheslav Turovskyi
Viacheslav Turovskyi

πŸ’» πŸš‡ πŸ“– 🚧 πŸ‘€ πŸ€”
Lukasz Gornicki
Lukasz Gornicki

πŸš‡ πŸ‘€
Akshat Nema
Akshat Nema

πŸ’»
sambhavgupta0705
sambhavgupta0705

πŸ’»

This project follows the all-contributors specification. Contributions of any kind welcome!