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: stringnpm install @asyncapi/bundler
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));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)); 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. |
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!