n-pliashko / docgen Goto Github PK

AsyncAPI Documentation Generator

Use your AsyncAPI definition to generate beautiful
human-readable documentation for your API.

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: 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

The shortest possible syntax:

adg asyncapi.yaml

Specify where to put the generated documentation:

adg asyncapi.yaml -o ./docs

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 run npm install asyncapi-docgen in your terminal or add it to your package.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}`);
  }
})();

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);
  });

This package makes use of two different custom specification extensions:

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 is user.signup, the result of concatenating both, in the example above, would be my.company/user.signup and not my/company/user/signup. If you aim for the latter, your baseTopic should be my/company and your topic should be user/signup.

• Node.js v7.6+

Fran Méndez (@fmvilas)