asyncapi-docgen
v1.0.2AsyncAPI Documentation Generator
Use your AsyncAPI definition to generate beautiful
human-readable documentation for your API.
Install
To use it from the CLI:
npm install -g asyncapi-docgen
To use it as a module in your project:
npm install --save asyncapi-docgen
Usage
From the command-line interface (CLI)
Usage: adg [options] <asyncAPI>
Options:
-V, --version output the version number
-o, --output <outputDir> directory where to put the generated files (defaults to current directory)
-h, --help output usage information
Examples
The shortest possible syntax:
adg asyncapi.yaml
Specify where to put the generated documentation:
adg asyncapi.yaml -o ./docs
As a module in your project
Place a file called asyncapi.yaml
in the same directory as the following script, and then run it. You can obtain the content of the file from editor.asyncapi.org, not included here for brevity.
Note that you'll need to install
asyncapi-docgen
for it to work. Either runnpm install asyncapi-docgen
in your terminal or add it to yourpackage.json
file as a dependency.
const fs = require('fs');
const path = require('path');
const docs = require('asyncapi-docgen');
// Read file content
const asyncapi = fs.readFileSync(path.resolve(__dirname, 'asyncapi.yaml'), 'utf8');
(async function() {
try {
const html = await docs.generateFullHTML(asyncapi);
console.log('Done!');
console.log(html);
} catch (e) {
console.error(`Something went wrong: ${e.message}`);
}
})();
Using promises
const fs = require('fs');
const path = require('path');
const docs = require('asyncapi-docgen');
// Read file content
const asyncapi = fs.readFileSync(path.resolve(__dirname, 'asyncapi.yaml'), 'utf8');
docs
.generateFullHTML(asyncapi)
.catch((err) => {
console.error(`Something went wrong: ${err.message}`);
})
.then((html) => {
console.log('Done!');
console.log(html);
});
Custom specification extensions
This package makes use of two different custom specification extensions:
Extension | Path | Description |
---|---|---|
x-logo |
/info |
URL of the logo rendered on the top left corner of the documentation. |
x-topic-separator |
/ |
A string to use as the topic separator. |
Examples
Custom logo:
asyncapi: '1.0.0'
info:
title: My API
x-logo: https://your-company.com/logo.png
MQTT-style topic separator:
asyncapi: '1.0.0'
x-topic-separator: '/'
ATTENTION: This will not replace your topic separators. E.g., if your baseTopic is
my.company
and one of your topics isuser.signup
, the result of concatenating both, in the example above, would bemy.company/user.signup
and notmy/company/user/signup
. If you aim for the latter, your baseTopic should bemy/company
and your topic should beuser/signup
.
Requirements
- Node.js v7.6+
Author
Fran Méndez (@fmvilas)
Metadata
- Unknown
- Whatever
- Fran Mendez
- released 7/26/2017