@asyncapi/generator 1.9.13 → 1.9.15

package/CODEOWNERS

@@ -6,4 +6,7 @@
 
 # The default owners are automatically added as reviewers when you open a pull request unless different owners are specified in the file.
 
+# All .md files
+*.md @Florence-Njeri @pratik2315
+
 * @fmvilas @derberg @magicmatatjahu @jonaslagoni @asyncapi-bot-eve

package/README.md

@@ -12,16 +12,8 @@
 - [List of official generator templates](#list-of-official-generator-templates)
 - [Requirements](#requirements)
 - [Using from the command-line interface (CLI)](#using-from-the-command-line-interface-cli)
-  * [Install the CLI](#install-the-cli)
-  * [Update the CLI](#update-the-cli)
+  * [CLI installation](#cli-installation)
   * [CLI usage](#cli-usage)
-  * [Global templates installed with yarn or npm](#global-templates-installed-with-yarn-or-npm)
-  * [CLI usage examples](#cli-usage-examples)
-  * [CLI usage with Docker](#cli-usage-with-docker)
-  * [CLI usage with npx instead of npm](#cli-usage-with-npx-instead-of-npm)
-- [Using as a module/package](#using-as-a-modulepackage)
-  * [Install the module](#install-the-module)
-  * [Example using the module](#example-using-the-module)
 - [Generator version vs Template version](#generator-version-vs-template-version)
 - [How to create a template](#how-to-create-a-template)
 - [Contributing](#contributing)
@@ -67,221 +59,20 @@ You can find above templates and the ones provided by the community in **[this l
 
 Install both packages using [official installer](https://nodejs.org/en/download/). After installation make sure both packages have proper version by running `node -v` and `npm -v`. To upgrade invalid npm version run `npm install npm@latest -g`
 
-> Generator is tested at the moment against Node 14 and NPM 6. Using newer versions is enabled but we do not guarantee they work well. Please provide feedback on the issues.
+> The generator is tested at the moment against Node 14 and NPM 6. Using newer versions is enabled but we don't guarantee they work well. Please provide feedback via issues.
 
 ## Using from the command-line interface (CLI)
 
-### Install the CLI
-
-To use it as CLI, install generator globally:
-
-```bash
-npm install -g @asyncapi/generator
-```
-
-### Update the CLI
-
-You might want to update your local installation of generator for different reasons:
-
-* You want the latest generator to have its latest features. Perform usual installation and in case you had generator installed already, it will upgrade to latest available:
-    ```bash
-    npm install -g @asyncapi/generator
-    ```
-* You want a specific version of the generator because your template might not be compatible with the latest generator. Check [what version you need](https://github.com/asyncapi/generator/releases) and perform installation, specifying the exact version with the `@` character:
-    ```bash
-    npm install -g @asyncapi/generator@0.50.0
-    ```
-
-> Sometimes you have to force additional npm installation like this: `npm install -g --force @asyncapi/generator`
-
-### CLI usage
-
-```bash
-Usage: ag [options] <asyncapi> <template>
-
-- <asyncapi>: Local path or URL pointing to AsyncAPI specification file
-- <template>: Name of the generator template like for example @asyncapi/html-template or https://github.com/asyncapi/html-template
-
-Options:
-  -V, --version                  output the version number
-  -d, --disable-hook [hooks...]  disable a specific hook type or hooks from given hook type
-  --debug                        enable more specific errors in the console
-  -i, --install                  installs 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 where to put the generated files (defaults to current directory)
-  -p, --param <name=value>       additional param to pass to templates
-  --force-write                  force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir (defaults to false)
-  --watch-template               watches the template directory and the AsyncAPI document, and re-generate 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
-```
-
-<details>
-  <summary>Click here to read more about supported values for the <code>&lt;template&gt;</code> parameter.</summary>
-  <br>
-  Templates are installable npm packages. Therefore, the value of <code>&lt;template&gt;</code> can be anything supported by <code>npm install</code>. Here's a summary of the possibilities:
-  <br><br>
-  <pre><code>
-  npm install [&lt;@scope&gt;/]&lt;name&gt;
-  npm install [&lt;@scope&gt;/]&lt;name&gt;@&lt;tag&gt;
-  npm install [&lt;@scope&gt;/]&lt;name&gt;@&lt;version&gt;
-  npm install [&lt;@scope&gt;/]&lt;name&gt;@&lt;version range&gt;
-  npm install &lt;git-host&gt;:&lt;git-user&gt;/&lt;repo-name&gt;
-  npm install &lt;git repo url&gt;
-  npm install &lt;tarball file&gt;
-  npm install &lt;tarball url&gt;
-  npm install &lt;folder&gt;</code></pre>
-</details>
-<br>
+### CLI installation
+Learn to install the AsyncAPI CLI from the [installation guide](docs/installation-guide.md).
 
-### Global templates installed with yarn or npm
+### CLI usage 
 
-You can preinstall templates globally. The generator first tries to locate template in local dependencies and then in location where global packages are installed.
-
-```bash
-npm install -g @asyncapi/html-template@0.16.0
-ag asyncapi.yaml @asyncapi/html-template
-# The generator uses template in version 0.16.0 and not latest
-```
-
-### CLI usage examples
-
-**The shortest possible syntax:**
-```bash
-ag asyncapi.yaml @asyncapi/html-template
-```
-
-**Generating from a URL:**
-```bash
-ag https://bit.ly/asyncapi @asyncapi/html-template
-```
-
-**Specify where to put the result:**
-```bash
-ag asyncapi.yaml @asyncapi/html-template -o ./docs
-```
-
-**Passing parameters to templates:**
-```bash
-ag 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
-ag 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
-ag 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
-ag asyncapi.yaml https://github.com/asyncapi/html-template.git
-```
-
-**Map schema references from baseUrl to local folder:**
-```bash
-ag 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
-
-Install [Docker](https://docs.docker.com/get-docker/) first. Thanks to Docker you do not need Node.js even though the generator is written with it.
-
-```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 generator directory after cloning this repository. First you specify mount in location of your AsyncAPI specification file and then you mount in directory where 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
-
-The [npx](https://www.npmjs.com/package/npx) is very useful when you want to run Generator in CI/CD environment. In such a scenario, you do not want to install generator globally and most environments that provide Node.js and npm, also provide npx out of the box.
-
-```bash
-npx -p @asyncapi/generator ag ./asyncapi.yaml @asyncapi/html-template
-```
-
-## Using as a module/package
-
-### Install the module
-
-```bash
-npm install @asyncapi/generator --save
-```
-
-### Example using the module 
-
-Below you can find an example of HTML generation using official `@asyncapi/html-template` template and fetching the spec document from server like `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 [API documentation](docs/api.md) for more example and full API reference information.
+Learn more about different ways of using the CLI from the [usage document](docs/usage.md).
 
 ## Generator version vs Template version
 
-The Generator is a tool that you can use to generate whatever you want, taking an AsyncAPI specification file as the input. A template is a tool that uses Generator features and helpers to specify what should be generated.
-
-In other words, a template depends on the Generator and its features. For example, it might work with the latest version of the Generator but not the previous ones. 
-
-The owner of the template specifies in the configuration what version of the Generator it is compatible with:
-```bash
-"generator": ">=0.50.0 <2.0.0",
-```
-
-The Generator doesn't work in case the template is not compatible:
-```bash
-Something went wrong:
-Error: This template is not compatible with the current version of the generator (0.50.0). This template is compatible with the following version range: >=0.60.0 <2.0.0.
-    at Generator.validateTemplateConfig (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:678:13)
-    at Generator.loadTemplateConfig (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:663:16)
-    at Generator.generate (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:146:18)
-    at processTicksAndRejections (internal/process/task_queues.js:97:5)
-    at async /Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/cli.js:135:7
-```
-
-In case you use Generator CLI and a specific template on production, it is safer to lock to a specific version of the template and the Generator. 
-
-Instead of generating HTML with latest `html-template` and the generator CLI:
-```bash
-npm install -g @asyncapi/generator
-ag asyncapi.yaml @asyncapi/html-template -o ./docs
-```
-
-Generate HTML with the version of the `html-template` and the Generator CLI that you are happy with:
-```bash
-npm install -g @asyncapi/generator@0.50.0
-ag 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. Generator features are not important for you, just make sure to use a version compatible with the template.
+Learn more about versioning from the [versioning document](docs/versioning.md).
 
 ## How to create a template
 
@@ -318,6 +109,8 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
   </tr>
   <tr>
     <td align="center"><a href="https://github.com/lkmandy"><img src="https://avatars.githubusercontent.com/u/17765231?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Amanda  Shafack </b></sub></a><br /><a href="https://github.com/asyncapi/generator/commits?author=lkmandy" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/Florence-Njeri"><img src="https://avatars.githubusercontent.com/u/40742916?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Florence Njeri</b></sub></a><br /><a href="https://github.com/asyncapi/generator/commits?author=Florence-Njeri" title="Documentation">📖</a> <a href="https://github.com/asyncapi/generator/pulls?q=is%3Apr+reviewed-by%3AFlorence-Njeri" title="Reviewed Pull Requests">👀</a> <a href="#infra-Florence-Njeri" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#maintenance-Florence-Njeri" title="Maintenance">🚧</a></td>
+    <td align="center"><a href="https://unruffled-goodall-dd424e.netlify.app/"><img src="https://avatars.githubusercontent.com/u/77961530?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Pratik Haldankar</b></sub></a><br /><a href="https://github.com/asyncapi/generator/commits?author=pratik2315" title="Documentation">📖</a> <a href="https://github.com/asyncapi/generator/pulls?q=is%3Apr+reviewed-by%3Apratik2315" title="Reviewed Pull Requests">👀</a> <a href="#maintenance-pratik2315" title="Maintenance">🚧</a> <a href="#talk-pratik2315" title="Talks">📢</a></td>
   </tr>
 </table>
 

package/docs/README.md

@@ -1,15 +1,18 @@
 Table of Contents
 
 - [Introduction](index.md)
-- [AsyncAPI Specification File](asyncapi-file.md)
-- [Configuration File](configuration-file.md)
-- [Templates](template.md)
-- [Authoring Templates](authoring-templates.md)
-- [React Render Engine](react-render-engine.md)
-- [Nunjucks Render Engine](nunjucks-render-engine.md)
-- [AsyncAPI Context](asyncapi-context.md)
+- [Installation Guide](installation-guide.md)
+- [Usage](usage.md)
+- [AsyncAPI document](asyncapi-document.md)
+- [Template](template.md)
 - [Parser](parser.md)
+- [Generator version vs template version](versioning.md)
+- [Template Development](template-development.md)
+- [Configuration File](configuration-file.md)
+- [Template context](template-context.md)
+- [React render engine](react-render-engine.md)
+- [Nunjucks render engine](nunjucks-render-engine.md)
 - [Hooks](hooks.md)
-- [File Templates](file-templates.md)
-- [TypeScript Support](typescript-support.md)
+- [File templates](file-templates.md)
+- [TypeScript support](typescript-support.md)
 - [Special file names](special-file-names.md)