@asyncapi/generator 1.9.13 → 1.9.15

package/docs/usage.md

@@ -0,0 +1,151 @@
+---
+title: "Usage"
+weight: 30
+---
+
+There are two ways to use the generator:
+- [Generator CLI](#generator-cli)
+- [Generator library](#using-as-a-modulepackage)
+
+## Generator CLI
+```bash
+Usage: asyncapi generate fromTemplate <asyncapi> <template> [<options>]
+
+- <asyncapi>: Local path or URL pointing to AsyncAPI document for example https://bit.ly/asyncapi
+- <template>: Name of the generator template like for example @asyncapi/html-template or https://github.com/asyncapi/html-template
+
+- <options>:
+  -V, --version                  output the generator version
+  -d, --disable-hook [hooks...]  disable a specific hook type or hooks from a given hook type
+  --debug                        enable more specific errors in the console
+  -i, --install                  install the template and its dependencies (defaults to false)
+  -n, --no-overwrite <glob>      glob or path of the file(s) to skip when regenerating
+  -o, --output <outputDir>       directory to put the generated files (defaults to current directory)
+  -p, --param <name=value>       additional parameters to pass to templates
+  --force-write                  force writing of the generated files to a given directory even if it is a Git repository with unstaged files or not empty dir (defaults to false)
+  --watch-template               watches the template directory and the AsyncAPI document, and re-generates the files when changes occur. Ignores the output directory. This flag should be used only for template development.
+  --map-base-url <url:folder>    maps all schema references from base URL to local folder
+  -h, --help                     display help for command
+```
+
+All templates are installable npm packages. Therefore, the value of `template` can be anything supported by `npm install`. Here's a summary of the possibilities:
+```
+npm install [<@scope>/]<name>
+npm install [<@scope>/]<name>@<tag>
+npm install [<@scope>/]<name>@<version>
+npm install [<@scope>/]<name>@<version range>
+npm install <git-host>:<git-user>/<repo-name>
+npm install <git repo url>
+npm install <tarball file>
+npm install <tarball url>
+npm install <folder>
+```
+
+### Global templates installed with `yarn` or `npm`
+
+You can preinstall templates globally before installing the generator CLI. The generator first tries to locate the template in local dependencies; if absent it checks where the global generator packages are installed.
+
+```bash
+npm install -g @asyncapi/html-template@0.16.0
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template
+# The generator uses html-template version 0.16.0 and not the latest version.
+```
+
+### CLI usage examples
+
+**The shortest possible syntax:**
+```bash
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template
+```
+
+**Generating from a URL:**
+```bash
+asyncapi generate fromTemplate https://bit.ly/asyncapi @asyncapi/html-template
+```
+
+**Specify where to put the result:**
+```bash
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs
+```
+
+**Passing parameters to templates:**
+```bash
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs -p title='Hello from param'
+```
+
+In the template you can use it like this: ` {{ params.title }}`
+
+**Disabling the hooks:**
+```bash
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs -d generate:before generate:after=foo,bar
+```
+
+The generator skips all hooks of the `generate:before` type and `foo`, `bar` hooks of the `generate:after` type.
+
+**Installing the template from a folder:**
+```bash
+asyncapi generate fromTemplate asyncapi.yaml ~/my-template
+```
+
+It creates a symbolic link to the target directory (`~/my-template` in this case). 
+
+**Installing the template from a git URL:**
+```bash
+asyncapi generate fromTemplate asyncapi.yaml https://github.com/asyncapi/html-template.git
+```
+
+**Map schema references from baseUrl to local folder:**
+```bash
+asyncapi generate fromTemplate test/docs/apiwithref.json @asyncapi/html-template -o ./build/ --force-write --map-base-url https://schema.example.com/crm/:./test/docs/
+```
+
+The parameter `--map-base-url` maps external schema references to local folders.
+
+### CLI usage with Docker
+
+When using our docker image that we regularly update, you don't need to install Node.js or Npm, even though the generator is written with it since the Docker image has the generator installed.
+
+Install [Docker](https://docs.docker.com/get-docker/) first, then use docker to pull and run the image using the following command:
+
+```bash
+docker run --rm -it \
+-v [ASYNCAPI SPEC FILE LOCATION]:/app/asyncapi.yml \
+-v [GENERATED FILES LOCATION]:/app/output \
+asyncapi/generator [COMMAND HERE]
+
+# Example that you can run inside the generator directory after cloning this repository. First, you specify the mount in the location of your AsyncAPI specification file and then you mount it in the directory where the generation result should be saved.
+docker run --rm -it \
+-v ${PWD}/test/docs/dummy.yml:/app/asyncapi.yml \
+-v ${PWD}/output:/app/output \
+asyncapi/generator -o /app/output /app/asyncapi.yml @asyncapi/html-template --force-write
+```
+
+### CLI usage with `npx` instead of `npm`
+
+[npx](https://www.npmjs.com/package/npx) is very useful when you want to run the generator in a CI/CD environment. In such a scenario, do not install the generator globally because most environments that provide Node.js and Npm, also provide npx out of the box. 
+
+Use the following npx command on your terminal:
+
+```bash
+npx -p @asyncapi/cli asyncapi generate fromTemplate ./asyncapi.yaml @asyncapi/html-template
+```
+
+## Using as a module/package
+Once you install the generator in your project, you can use it to generate whatever you want. The following code snippet is an example of HTML generation using the official `@asyncapi/html-template` template and fetching the spec document from the server using:
+```
+https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml
+```
+
+```js
+const path = require('path');
+const generator = new Generator('@asyncapi/html-template', path.resolve(__dirname, 'example'));
+
+try {
+  await generator.generateFromURL('https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml');
+  console.log('Done!');
+} catch (e) {
+  console.error(e);
+}
+```
+
+See the [API documentation](api.md) for more examples and full API reference information.

package/docs/versioning.md

@@ -0,0 +1,31 @@
+---
+title: "Generator version vs template version"
+weight: 70
+---
+
+The generator tool generates whatever you want, as long as it can be defined in a template based on the [AsyncAPI document](asyncapi-document). On the other hand, a **template** is a file or group of files that specify the kind of output you expect from using the generator's features. For example, you may want to use the [NodeJS template](https://github.com/asyncapi/nodejs-template) to generate boilerplate code for your message-based APIs.
+
+Templates are dependent on the generators' features. For example, the template you want to use may be compatible with the latest generator version but incompatible with the previous versions. Check the configuration file or ReadME of the template to see the version of the generator it supports. The generator has an `isTemplateCompatible` function that checks if the template is compatible with the version of the generator you want to use. If the template isn't compatible, you will see a terminal error output similar to the following:
+```
+Something went wrong:
+Error: This template is not compatible with the current version of the generator (${generatorVersion}). This template is compatible with the following version range: ${generator}.`)
+```
+
+> Use the following command to check the version of the AsyncAPI CLI you have installed;  `asyncapi --version`
+
+It is better to lock a specific version of the template and the generator if you plan to use the AsyncAPI CLI and a particular template in production. The differences between using the version of the AsyncAPI CLI you have installed and locking a certain version on production are demonstrated in the following code snippets.
+
+Generate HTML with the latest AsyncAPI CLI using the html-template.
+```
+npm install -g @asyncapi/cli
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs
+```
+
+Generate HTML using a particular version of the AsyncAPI CLI using the html-template.
+
+```
+npm install -g @asyncapi/cli@0.20.0
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@0.7.0 -o ./docs
+```
+
+> Before using newer versions of the template, always look at the [changelog](https://github.com/asyncapi/html-template/releases) first. If the generator's features are not important to you, just make sure to use a version compatible with your template.

package/lib/generator.js

@@ -334,11 +334,11 @@ class Generator {
    * Returns the content of a given template file.
    *
    * @example
-   * const Generator = require('asyncapi-generator');
+   * const Generator = require('@asyncapi/generator');
    * const content = await Generator.getTemplateFile('@asyncapi/html-template', 'partials/content.html');
    *
    * @example <caption>Using a custom `templatesDir`</caption>
-   * const Generator = require('asyncapi-generator');
+   * const Generator = require('@asyncapi/generator');
    * const content = await Generator.getTemplateFile('@asyncapi/html-template', 'partials/content.html', '~/my-templates');
    *
    * @static

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asyncapi/generator",
-  "version": "1.9.13",
+  "version": "1.9.15",
   "description": "The AsyncAPI generator. It can generate documentation, code, anything!",
   "main": "./lib/generator.js",
   "bin": {
@@ -18,7 +18,7 @@
     "test:integration": "npm run test:cleanup && jest --testPathPattern=integration --modulePathIgnorePatterns='./__mocks__'",
     "test:cli": "node cli.js ./test/docs/dummy.yml @asyncapi/html-template -o test/output --force-write --debug && test -e test/output/index.html",
     "test:cleanup": "rimraf \"test/temp\"",
-    "docs": "jsdoc2md lib/generator.js > docs/api.md",
+    "docs": "jsdoc2md --partial docs/jsdoc2md-handlebars/custom-sig-name.hbs docs/jsdoc2md-handlebars/main.hbs docs/jsdoc2md-handlebars/docs.hbs docs/jsdoc2md-handlebars/header.hbs docs/jsdoc2md-handlebars/defaultvalue.hbs docs/jsdoc2md-handlebars/link.hbs docs/jsdoc2md-handlebars/params-table.hbs --files lib/generator.js > docs/api.md",
     "docker:build": "docker build -t asyncapi/generator:latest .",
     "lint": "eslint --max-warnings 0 --config .eslintrc .",
     "lint:tpl:validator": "eslint --fix --config .eslintrc .github/templates-list-validator",
@@ -73,8 +73,8 @@
     "semver": "^7.3.2",
     "simple-git": "^3.3.0",
     "source-map-support": "^0.5.19",
-    "ts-node": "^9.1.1",
-    "typescript": "^4.2.2"
+    "ts-node": "^10.9.1",
+    "typescript": "^4.9.3"
   },
   "devDependencies": {
     "eslint": "^6.8.0",

package/.releaserc

@@ -1,10 +0,0 @@
----
-branches:
-- master
-plugins:
-- - "@semantic-release/commit-analyzer"
-  - preset: conventionalcommits
-- - "@semantic-release/release-notes-generator"
-  - preset: conventionalcommits
-- "@semantic-release/npm"
-- "@semantic-release/github"

package/docs/asyncapi-context.md

@@ -1,6 +0,0 @@
----
-title: "AsyncAPI Context"
-weight: 80
----
-
->This document is under construction.

package/docs/asyncapi-file.md

@@ -1,6 +0,0 @@
----
-title: "AsyncAPI Specification File"
-weight: 20
----
-
->This document is under construction.

package/docs/authoring-templates.md

@@ -1,17 +0,0 @@
----
-title: "Authoring Templates"
-weight: 50
----
-
-The AsyncAPI generator has been built with extensibility in mind. The package uses a set of default templates to let you generate documentation and code. However, you can create and use your own templates. In this section, you learn how to create your own one.
-
-To work on a template, you need an AsyncAPI specification file that you can use for testing. For this purpose, you can use [this](../test/docs/dummy.yml) dummy file as it's purpose is to cover as many features of AsyncAPI as possible. Do not copy this file to your template but use it directly from this repo like this: `ag https://raw.githubusercontent.com/asyncapi/generator/master/test/docs/dummy.yml ./your-template`
-
-> In case you find some features missing or other possible improvements in the dummy file, suggest changes. The goal is to build a file that all templates can use and check their specification features coverage.
-
-1. A template is a directory in your file system.
-1. The template can have own dependencies. Just create `package.json` for the template. The generator makes sure to trigger the installation of dependencies.
-1. Templates can be configured. Configuration must be stored in the `package.json` file under custom `generator` property. [Read more about the configuration file](#configuration-file).
-1. The template engine can be either [React](#react) (recommended) or [Nunjucks](#nunjucks) (default). This can be controlled with the `renderer` property in the [template configuration](#template-configuration).
-1. Templates may contain `hooks` that are functions invoked during specific moment of the generation. In the template, they must be stored in the `hooks` directory under the template directory. They can also be stored in other modules and external libraries and configured inside the template [Read more about hooks](#hooks).
-1. There are parameters with special meaning. [Read more about special parameters](#special-parameters).