The bundler from snakedoc

Overview
Installation
Usage
- Resolving external references into components
bundle(files, [options])
Contributors

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 💻 🤔 🎨 👀 🚧 📖	_{Maciej Urbańczyk} 🤔 👀	_{Mohd Toukir Khan} 🚇	_MrYugs 📖
_{Amanpreet Singh Bedi} 📖	_{Alexey Vasilevich} 📖	_{Viacheslav Turovskyi} 💻 🚇 📖 🚧 👀 🤔	_{Lukasz Gornicki} 🚇 👀
_{Akshat Nema} 💻	_{sambhavgupta0705} 💻