` component that enables you to provide the name of resulting file and the content of the model. Notice also `model.result` that shows that initially generated array with models did not contain raw models content but a set of output objects that contain not only `result` but also other info, like for example `modelName`.
With such a model template that uses Modelina, as a result of generation process you would receive a set of model files in `$OUTPUT_DIR/src/models` directory.
diff --git a/apps/generator/docs/nunjucks-render-engine.md b/apps/generator/docs/nunjucks-render-engine.md
index 34626b49b..316f52a82 100644
--- a/apps/generator/docs/nunjucks-render-engine.md
+++ b/apps/generator/docs/nunjucks-render-engine.md
@@ -12,7 +12,7 @@ weight: 120
1. Templates may contain multiple files. Unless stated otherwise, all files will be rendered.
1. The default variables you have access to in any the template file are the following:
- `asyncapi` that is a parsed spec file object. Read the [API](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#asyncapidocument) of the Parser to understand what structure you have access to in this parameter.
- - `originalAsyncAPI` that is an original spec file before it is parsed.
+ - `originalAsyncAPI` that is an original spec file before it is parsed.
- `params` that contain the parameters provided when generating.
### Partials
@@ -20,18 +20,18 @@ weight: 120
Files from the `.partials` directory do not end up with other generated files in the target directory. In this directory you should keep reusable templates chunks that you can [include](https://mozilla.github.io/nunjucks/templating.html#include) in your templates. You can also put there [macros](https://mozilla.github.io/nunjucks/templating.html#macro) to use them in templates, like in below example:
```html
-{# tags.html #}
-{% macro tags(tagList) %}
+{# tags.html #} {% macro tags(tagList) %}
{% for tag in tagList %}
- {{tag.name()}}
+ {{tag.name()}}
{% endfor %}
-{% endmacro %}
-
-{# operations.html #}
-{% from "./tags.html" import tags %}
-{{ tags(operation.tags()) }}
+{% endmacro %} {# operations.html #} {% from "./tags.html" import tags %} {{
+tags(operation.tags()) }}
```
### Filters
@@ -52,7 +52,7 @@ const filter = module.exports;
async function asyncCamelCase(str, callback) {
try {
const result = // logic for camel casing str
- callback(null, result);
+ callback(null, result);
} catch (error) {
callback(error);
}
@@ -60,7 +60,11 @@ async function asyncCamelCase(str, callback) {
filter.renderAsyncContent = renderAsyncContent;
// using in template
-{{ channelName | asyncCamelCase }}
+{
+ {
+ channelName | asyncCamelCase;
+ }
+}
```
Unfortunately, if you need to use Promise, filter still must be annotated with the `async` keyword:
@@ -75,5 +79,4 @@ async function asyncCamelCase(str, callback) {
In case you have more than one template and want to reuse filters, you can put them in a single library. You can configure such a library in the template configuration under `filters` property. To learn how to add such filters to configuration [read more about the configuration file](#configuration-file).
-
-You can also use the official AsyncAPI [nunjucks-filters](/apps/nunjucks-filters) that are by default included in the generator library.
\ No newline at end of file
+You can also use the official AsyncAPI [nunjucks-filters](/apps/nunjucks-filters) that are by default included in the generator library.
diff --git a/apps/generator/docs/parser.md b/apps/generator/docs/parser.md
index 399308d67..6f1ff86b9 100644
--- a/apps/generator/docs/parser.md
+++ b/apps/generator/docs/parser.md
@@ -5,7 +5,7 @@ weight: 60
## Parser
-The AsyncAPI Parser is a package used to parse and validate the [AsyncAPI documents](asyncapi-document) in your Node.js or browser application. These documents can be either in YAML or JSON format.
+The AsyncAPI Parser is a package used to parse and validate the [AsyncAPI documents](asyncapi-document.md) in your Node.js or browser application. These documents can be either in YAML or JSON format.
The Parser validates these documents using dedicated schema-supported plugins.
@@ -19,7 +19,7 @@ Supported schemas:
The Parser allows the template developer to easily access schemas provided in the above supported formats. This is because the JavaScript parser converts all of them into JSON schema.
-If the document is valid, the Parser returns an `AsyncAPIDocument instance` with a set of helper functions that enable easier access to the contents of the AsyncAPI document. The parser provides dereferenced output. During the dereference process, the AsyncAPI parser substitutes a reference with a full definition. The dereferenced output is always in JSON format. The parser provides a message listing all errors if a document is invalid. The original AsyncAPI document is part of the [Template Context](template-context) as the generator also passes the original AsyncAPI document to the template context.
+If the document is valid, the Parser returns an `AsyncAPIDocument instance` with a set of helper functions that enable easier access to the contents of the AsyncAPI document. The parser provides dereferenced output. During the dereference process, the AsyncAPI parser substitutes a reference with a full definition. The dereferenced output is always in JSON format. The parser provides a message listing all errors if a document is invalid. The original AsyncAPI document is part of the [Template Context](template-context.md) as the generator also passes the original AsyncAPI document to the template context.
The following AsyncAPI document example has two channels: `channelOne` and `channelTwo`. Each channel has one operation and a single message:
@@ -81,7 +81,7 @@ const messages = asyncAPIDocument.allMessages();
- `invalid-yaml`
- `impossible-to-convert-to-json`
1. If the document is valid, the Parser modifies the AsyncAPI document, returns a set of helper functions, and bundles them together into the **asyncapi** variable. These helper functions in the form of an **asyncapi** variable are passed to the **Template Context**.
-1. The Template Context passes all of these values to the [**Render Engine**](react-render-engine) of your choice. Finally, the Render Engine generates whatever output you may have specified in your template. (i.e. code, documentation, diagrams, pdfs, applications, etc.)
+1. The Template Context passes all of these values to the [**Render Engine**](react-render-engine.md) of your choice. Finally, the Render Engine generates whatever output you may have specified in your template. (i.e. code, documentation, diagrams, pdfs, applications, etc.)
```mermaid
graph TD
diff --git a/apps/generator/docs/react-render-engine.md b/apps/generator/docs/react-render-engine.md
index 1cf74b983..18bca3d6f 100644
--- a/apps/generator/docs/react-render-engine.md
+++ b/apps/generator/docs/react-render-engine.md
@@ -5,14 +5,14 @@ weight: 110
[React](https://reactjs.org) is the render engine that we strongly suggest you should use for any new templates. The only reason it is not the default render engine is to stay backward compatible.
-* It enables the possibility of [debugging](#debugging-react-template) your template (this is not possible with Nunjucks).
-* It provides better error stack traces.
-* Provides better support for separating code into more manageable chunks/components.
-* The readability of the template is much better compared to Nunjucks syntax.
-* Better tool support for development.
-* Introduces testability of components which is not possible with Nunjucks.
-
-When writing React templates you decide whether to use CommonJS, ES5, or ES6 modules since everything is bundled together before the rendering process takes over. We use our own React renderer which can be found in the [Generator React SDK](https://github.com/asyncapi/generator-react-sdk).
+- It enables the possibility of [debugging](#debugging-react-template) your template (this is not possible with Nunjucks).
+- It provides better error stack traces.
+- Provides better support for separating code into more manageable chunks/components.
+- The readability of the template is much better compared to Nunjucks syntax.
+- Better tool support for development.
+- Introduces testability of components which is not possible with Nunjucks.
+
+When writing React templates you decide whether to use CommonJS, ES5, or ES6 modules since everything is bundled together before the rendering process takes over. We use our own React renderer which can be found in the [Generator React SDK](https://github.com/asyncapi/generator-react-sdk).
There you can find information about how the renderer works or how we transpile your template files.
Your React template always requires `@asyncapi/generator-react-sdk` as a dependency. `@asyncapi/generator-react-sdk` is required to access the `File` component which is required as a root component for a file to be rendered. Furthermore, it provides some common components to make your development easier, like `Text` or `Indent`.
@@ -22,7 +22,7 @@ Let's consider a basic React template as the one below called `MyTemplate.js`:
```js
import { File, Text } from "@asyncapi/generator-react-sdk";
-export default function({ asyncapi, params, originalAsyncAPI }) {
+export default function ({ asyncapi, params, originalAsyncAPI }) {
return (
Some text that should render as is
@@ -31,21 +31,21 @@ export default function({ asyncapi, params, originalAsyncAPI }) {
}
```
-The exported default function returns a `File` component as a root component which the generator uses to determine what file should be generated. In our case, we overwrite the default functionality of saving the file as `MyTemplate.js` but instead use the filename `asyncapi.md`. It is then specified that we should render `Some text that should render as is\n` within that file. Notice the `\n` character at the end, which is automatically added after the `Text` component.
+The exported default function returns a `File` component as a root component which the generator uses to determine what file should be generated. In our case, we overwrite the default functionality of saving the file as `MyTemplate.js` but instead use the filename `asyncapi.md`. It is then specified that we should render `Some text that should render as is\n` within that file. Notice the `\n` character at the end, which is automatically added after the `Text` component.
For further information about components, props, etc, see the [Generator React SDK](https://github.com/asyncapi/generator-react-sdk)
### Common assumptions
1. Generator renders all files located in the `template` directory if they meet the following conditions:
- - `File` is the root component
- - The file is not in the list of `nonRenderableFiles` in the template configuration
+ - `File` is the root component
+ - The file is not in the list of `nonRenderableFiles` in the template configuration
1. New lines are automatically added after each `Text` component.
1. The props you have access to in the rendering function are:
- `asyncapi` which is a parsed spec file object. Read the [API](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#asyncapidocument) of the Parser to understand what structure you have access to in this parameter.
- - `originalAsyncAPI` which is an original spec file before it is parsed.
+ - `originalAsyncAPI` which is an original spec file before it is parsed.
- `params` that contain the parameters provided when generating.
-1. All the file templates are supported where the variables are provided after the default props as listed above.
+1. All the file templates are supported where the variables are provided after the default props as listed above.
### Debugging React template in VSCode
@@ -76,5 +76,3 @@ With React, it enables you to debug your templates. For Visual Studio Code, we h
```
Now replace `./asyncapi.yml` with your document of choice. Replace `./template` with the path to your React template. You can now debug your template by adding any breakpoints you want and inspecting your code.
-
-
diff --git a/apps/generator/docs/special-file-names.md b/apps/generator/docs/special-file-names.md
index 536eee841..2c2b77119 100644
--- a/apps/generator/docs/special-file-names.md
+++ b/apps/generator/docs/special-file-names.md
@@ -5,7 +5,7 @@ weight: 160
We use NPM behind the scenes to download and install the templates. Since NPM will not fetch files like `.gitignore`, you should name them differently. Luckily, the Generator will take care of renaming them back for you. The following is a table of the special file names:
-|Special file name|Output file name|
-|---|---|
-|`{.gitignore}`|`.gitignore`|
-|`{.npmignore}`|`.npmignore`|
\ No newline at end of file
+| Special file name | Output file name |
+| ----------------- | ---------------- |
+| `{.gitignore}` | `.gitignore` |
+| `{.npmignore}` | `.npmignore` |
diff --git a/apps/generator/docs/template-context.md b/apps/generator/docs/template-context.md
index b6b01fd94..89cce3f4f 100644
--- a/apps/generator/docs/template-context.md
+++ b/apps/generator/docs/template-context.md
@@ -4,17 +4,18 @@ weight: 100
---
While using the generator tool, you may want dynamic values populated to your templates and rendered in the output. The generator can achieve that using the **template context**.
-The **template context** allows you to access the contents of the [AsyncAPI document](asyncapi-document) and inject dynamic values to the template files passed to the asyncAPI CLI during the generation process. The render engine then displays these dynamically assigned values in the output.
+The **template context** allows you to access the contents of the [AsyncAPI document](asyncapi-document.md) and inject dynamic values to the template files passed to the asyncAPI CLI during the generation process. The render engine then displays these dynamically assigned values in the output.
## Generation process
+
1. The **Generator** receives **Template** and **params** as input.
-2. The **Generator** sends to the **Parser** the **asyncapiString** which is a stringified version of the original **AsyncAPI document**.
+2. The **Generator** sends to the **Parser** the **asyncapiString** which is a stringified version of the original **AsyncAPI document**.
3. The **Parser** validates the format of the **asyncapiString** using OpenAPI, RAML, or Avro schemas.
4. If the **asyncapiString** is valid, the **parser** manipulates it, returns a set of helper functions and properties, and bundles them into an **asyncapi** variable. The **asyncapi** variable is an instance of the **AsyncAPI document**. The helper functions and properties make it easier to access the contents of the **AsyncAPI document** in the template.
5. The **Generator** then passes the **params**, which are template-specific options used to customize the output, the **Template files**, and the **asyncapi** which collectively make up the **Template Context**.
6. The **Template Context** is then passed to the **Render Engine**. The **Render Engine** then injects all the dynamic values from the **Template Context** into the **Template files**.
-
-``` mermaid
+
+```mermaid
graph LR
A[Template Context]
B{Generator}
@@ -34,8 +35,9 @@ graph LR
```
## Template context
+
The extra context passed to the render engine during the generation process and made accessible in the templates includes:
- **`originalAsyncAPI`** is a stringified version of the original AsyncAPI document that the user passed to the Generator.
- **`asyncapi`** is a parsed AsyncAPI document with helper functions and properties. You should use it to access document contents e.g `asyncapi.title`.
-- **`params`** is an object with all the parameters passed to the Generator by the user.
\ No newline at end of file
+- **`params`** is an object with all the parameters passed to the Generator by the user.
diff --git a/apps/generator/docs/template-development.md b/apps/generator/docs/template-development.md
index 423222505..d96d12fbd 100644
--- a/apps/generator/docs/template-development.md
+++ b/apps/generator/docs/template-development.md
@@ -2,6 +2,7 @@
title: "Template development"
weight: 80
---
+
> **Note**
> It is advised against attempting to manually template types and models from scratch using the AsyncAPI templating engines such as Nunjucks and React render engines. Instead, it is recommended to use [AsyncAPI Modelina](/docs/tools/generator/model-generation) a dedicated library for model generation.
@@ -16,6 +17,7 @@ Let's break down the minimum template requirements: the `template` directory and
The `template` directory holds all the files that will be used for generating the output. The generator will process all the files stored in this directory.
The following code is an example of an `index.js` file inside the `template` folder.
+
```js
import { File, Text } from "@asyncapi/generator-react-sdk";
@@ -35,7 +37,7 @@ The above example will produce an `asyncapi.md` file where usage of the AsyncAPI
Before the generation process begins, the generator installs the template into its dependencies. A `package.json` file is necessary to identify the template name.
-The following block shows an example `package.json` file that points to the [React Render Engine](react-render-engine) and necessary dependencies:
+The following block shows an example `package.json` file that points to the [React Render Engine](react-render-engine.md) and necessary dependencies:
```json
{
@@ -55,20 +57,20 @@ Every template must depend on the [`@asyncapi/generator-react-sdk` package](http
You must configure the generator's `package.json` file to contain JSON objects with the required parameters for template configuration, such as:
-|Name|Type|Description|
-|---|---|---|
-|`renderer`| String | Its value can be either `react` or `nunjucks` (default).
-|`supportedProtocols`| [String] | A list with all the protocols this template supports.
-|`parameters`| Object[String, Object] | An object with all the parameters that can be passed when generating the template. When using the command line, it's done by indicating `--param name=value` or `-p name=value`.
-|`parameters[param].description`| String | A user-friendly description about the parameter.
-|`parameters[param].default`| Any | Default value of the parameter if not specified. Shouldn't be used for mandatory `required=true` parameters.
-|`parameters[param].required`| Boolean | Whether the parameter is required or not.
+| Name | Type | Description |
+| ------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `renderer` | String | Its value can be either `react` or `nunjucks` (default). |
+| `supportedProtocols` | [String] | A list with all the protocols this template supports. |
+| `parameters` | Object[String, Object] | An object with all the parameters that can be passed when generating the template. When using the command line, it's done by indicating `--param name=value` or `-p name=value`. |
+| `parameters[param].description` | String | A user-friendly description about the parameter. |
+| `parameters[param].default` | Any | Default value of the parameter if not specified. Shouldn't be used for mandatory `required=true` parameters. |
+| `parameters[param].required` | Boolean | Whether the parameter is required or not. |
The above table lists some configuration options that help the generator achieve a specific set of tasks throughout the generation process. The `generator` property from 'package.json' contains all the configuration information. To learn more about template configuration and various supported parameters, read the [generator configuration file](configuration-file).
-> Whenever you make a change to the package.json, make sure you perform an update by running `npm install`; this command synchronizes with the `package-lock.json` and validates the file.
+> Whenever you make a change to the package.json, make sure you perform an update by running `npm install`; this command synchronizes with the `package-lock.json` and validates the file.
-### `package.json` configuration options
+### `package.json` configuration options
The following examples show some advanced configurations that we can use in our `package.json` file:
@@ -77,18 +79,17 @@ The following examples show some advanced configurations that we can use in our
"name": "myTemplate",
"generator": {
"renderer": "react",
- "supportedProtocols": [
- "mqtt"
- ]
+ "supportedProtocols": ["mqtt"]
},
"dependencies": {
"@asyncapi/generator-react-sdk": "^0.2.25"
}
}
```
-The above `package.json` file has a newly added configuration called `supportedProtocols` which is set to a list containing only `mqtt`. This configuration displays all the protocols that this template supports. You can have multiple supported protocols in our template.
-For example, if you want to generate an output using the above template, you need to have an AsyncAPI document with servers that use `mqtt` to generate your desired output. If your AsyncAPI document has server connections with `kafka`, the generation process will be terminated since the only supported protocol mentioned is `mqtt`.
+The above `package.json` file has a newly added configuration called `supportedProtocols` which is set to a list containing only `mqtt`. This configuration displays all the protocols that this template supports. You can have multiple supported protocols in our template.
+
+For example, if you want to generate an output using the above template, you need to have an AsyncAPI document with servers that use `mqtt` to generate your desired output. If your AsyncAPI document has server connections with `kafka`, the generation process will be terminated since the only supported protocol mentioned is `mqtt`.
### Accessing template parameters
@@ -99,14 +100,12 @@ Additionally, we can also have a configuration called `parameters`, which is an
"name": "myTemplate",
"generator": {
"renderer": "react",
- "supportedProtocols": [
- "mqtt"
- ],
+ "supportedProtocols": ["mqtt"],
"parameters": {
- "version": {
- "description": "Overrides application version under `info.version` in the AsyncAPI document.",
- "required": false
- }
+ "version": {
+ "description": "Overrides application version under `info.version` in the AsyncAPI document.",
+ "required": false
+ }
}
},
"dependencies": {
@@ -122,7 +121,7 @@ The changes done in the template will be as follows:
Original:
```js
-App name: **{ asyncapi.info().title() }**
+App name: **{asyncapi.info().title()}**
```
Newer:
@@ -145,12 +144,13 @@ Hooks help you change the specification version with the new `version` that you
```js
module.exports = {
- 'generate:before': ({ asyncapi, templateParams = {} }) => {
+ "generate:before": ({ asyncapi, templateParams = {} }) => {
const version = templateParams.version || asyncapi.info().version();
asyncapi._json.info.version = version;
- }
+ },
};
```
+
This can be an even better alternative to overriding the `version` parameter we discussed in the previous section. A markdown document will be generated, and the AsyncAPI document passed to the generator will be returned with the overwritten version.
The updated template looks like the following:
diff --git a/apps/generator/docs/template.md b/apps/generator/docs/template.md
index b8f31db01..9a452e227 100644
--- a/apps/generator/docs/template.md
+++ b/apps/generator/docs/template.md
@@ -5,7 +5,7 @@ weight: 50
## Template
-A template is a project that specifies the generation process output by using the AsyncAPI generator and an [AsyncAPI document](asyncapi-document). These files describe the generation results depending on the AsyncAPI document's content.
+A template is a project that specifies the generation process output by using the AsyncAPI generator and an [AsyncAPI document](asyncapi-document.md). These files describe the generation results depending on the AsyncAPI document's content.
Examples outputs:
@@ -18,13 +18,13 @@ A template is an independent Node.js project unrelated to the `generator` reposi
The generator uses the official [Arborist](https://www.npmjs.com/package/@npmcli/arborist) NPM library. (This means templates do not have to be published to package managers to use them.) Arborist helps the generator fetch the template's source code and use it for the generation process. By default, this library pulls data from the default NPM registry, which is https://registry.npmjs.org. You can also configure the generator to fetch templates that are private or hosted in different NPM registry
-You can store template projects on a local drive or as a `git` repository during the development process.
+You can store template projects on a local drive or as a `git` repository during the development process.
## Template generation process
1. Template is provided as input to the **Generator**.
2. **asyncapi** is the original AsyncAPI document injected into your template file by default.
-3. **params** are the parameters you pass to the AsyncAPI CLI. Later, you can also pass these **params** further to other components.
+3. **params** are the parameters you pass to the AsyncAPI CLI. Later, you can also pass these **params** further to other components.
4. The generator passes both the original **asyncapi**, the original AsyncAPI document, and the **params** to the **Template Context**.
5. Concurrently, the generator passes **Template files** to the **Render engine** as well. AsyncAPI uses two render engines — _react_ and _nunjucks_.
6. Once the Render Engine receives both the Template Files and the Template Context, it injects all the dynamic values into your react or nunjucks engine, based on the Template Files using the Template Context.
@@ -51,23 +51,22 @@ AsyncAPI has a list of available templates to enhance your generation process. T
-Template Name | Description | Source code
----|---|---
-`@asyncapi/nodejs-template` | Generates Node.js service that uses Hermes package | [Node.js template](https://github.com/asyncapi/nodejs-template)
-`@asyncapi/nodejs-ws-template` | Generates Node.js service that supports WebSocket protocol only | [Node.js WebSocket template](https://github.com/asyncapi/nodejs-ws-template)
-`@asyncapi/java-template` | Generates Java JMS application | [Java template](https://github.com/asyncapi/java-template)
-`@asyncapi/java-spring-template` | Generates Java Spring service | [Java spring template](https://github.com/asyncapi/java-spring-template)
-`@asyncapi/java-spring-cloud-stream-template` | Generates Java Spring Cloud Stream service | [Java spring cloud stream template](https://github.com/asyncapi/java-spring-cloud-stream-template)
-`@asyncapi/python-paho-template` | Generates Python service that uses Paho library | [Python paho template](https://github.com/asyncapi/python-paho-template)
-`@asyncapi/html-template` | Generates HTML documentation site | [HTML template](https://github.com/asyncapi/html-template)
-`@asyncapi/markdown-template` | Generates documentation in Markdown file | [Markdown template](https://github.com/asyncapi/markdown-template)
-`@asyncapi/ts-nats-template` | Generates TypeScript NATS client | [TypeScript/Node.js NATS template](https://github.com/asyncapi/ts-nats-template/)
-`@asyncapi/go-watermill-template` | Generates Go client using Watermill | [GO watermill template](https://github.com/asyncapi/go-watermill-template)
-`@asyncapi/dotnet-nats-template` | Generates .NET C# client using NATS | [.NET C# NATS template](https://github.com/asyncapi/dotnet-nats-template)
+| Template Name | Description | Source code |
+| --------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `@asyncapi/nodejs-template` | Generates Node.js service that uses Hermes package | [Node.js template](https://github.com/asyncapi/nodejs-template) |
+| `@asyncapi/nodejs-ws-template` | Generates Node.js service that supports WebSocket protocol only | [Node.js WebSocket template](https://github.com/asyncapi/nodejs-ws-template) |
+| `@asyncapi/java-template` | Generates Java JMS application | [Java template](https://github.com/asyncapi/java-template) |
+| `@asyncapi/java-spring-template` | Generates Java Spring service | [Java spring template](https://github.com/asyncapi/java-spring-template) |
+| `@asyncapi/java-spring-cloud-stream-template` | Generates Java Spring Cloud Stream service | [Java spring cloud stream template](https://github.com/asyncapi/java-spring-cloud-stream-template) |
+| `@asyncapi/python-paho-template` | Generates Python service that uses Paho library | [Python paho template](https://github.com/asyncapi/python-paho-template) |
+| `@asyncapi/html-template` | Generates HTML documentation site | [HTML template](https://github.com/asyncapi/html-template) |
+| `@asyncapi/markdown-template` | Generates documentation in Markdown file | [Markdown template](https://github.com/asyncapi/markdown-template) |
+| `@asyncapi/ts-nats-template` | Generates TypeScript NATS client | [TypeScript/Node.js NATS template](https://github.com/asyncapi/ts-nats-template/) |
+| `@asyncapi/go-watermill-template` | Generates Go client using Watermill | [GO watermill template](https://github.com/asyncapi/go-watermill-template) |
+| `@asyncapi/dotnet-nats-template` | Generates .NET C# client using NATS | [.NET C# NATS template](https://github.com/asyncapi/dotnet-nats-template) |
> Some of these templates are maintained by various third-party organizations. The README file usually contains this information and more, such as configuration options the user can pass to the template, usage, technical requirements, etc.
> Check out all our community [generator templates](https://github.com/search?q=topic%3Aasyncapi+topic%3Agenerator+topic%3Atemplate)
-
diff --git a/apps/generator/docs/typescript-support.md b/apps/generator/docs/typescript-support.md
index 5c785cd3c..6fc3ef9b3 100644
--- a/apps/generator/docs/typescript-support.md
+++ b/apps/generator/docs/typescript-support.md
@@ -9,5 +9,3 @@ The AsyncAPI generator has TypeScript support for [hooks](#hooks) and Nunjucks's
- Source code of the hook/filter must have `.ts` extension.
- Each package related to the typings for TypeScript like `@types/node` must be installed in the template under `dependencies` array. This is because the Generator transpiles the TypeScript code on-the-fly while rendering the template, and cannot use packages under `devDependencies`.
- Each template should have `@types/node` package installed to enable support for typings for Node.
-
-
diff --git a/apps/generator/docs/usage.md b/apps/generator/docs/usage.md
index 344044680..6965ce7fd 100644
--- a/apps/generator/docs/usage.md
+++ b/apps/generator/docs/usage.md
@@ -4,11 +4,14 @@ weight: 30
---
There are two ways to use the generator:
+
- [AsyncAPI CLI](#generator-cli)
- [Generator library](#using-as-a-modulepackage)
## AsyncAPI CLI
+
Generates whatever you want using templates compatible with AsyncAPI Generator.
+
```bash
USAGE
$ asyncapi generate fromTemplate [ASYNCAPI] [TEMPLATE] [-h] [-d ] [-i] [--debug] [-n ] [-o ] [--force-write] [-w] [-p ] [--map-base-url ]
@@ -34,6 +37,7 @@ EXAMPLES
```
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>/]
npm install [<@scope>/]@
@@ -59,21 +63,25 @@ asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template
### 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'
```
@@ -81,6 +89,7 @@ asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs -
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
```
@@ -88,18 +97,21 @@ asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs -
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).
+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/
```
@@ -124,11 +136,12 @@ docker run --rm -it \
-v ${PWD}/output:/app/output \
asyncapi/cli generate fromTemplate -o /app/output /app/asyncapi.yml @asyncapi/html-template --force-write
```
-Note: Use ``` ` ``` instead of `\` for Windows.
+
+Note: Use `` ` `` instead of `\` for Windows.
### 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.
+[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:
@@ -137,21 +150,28 @@ npx -p @asyncapi/cli asyncapi generate fromTemplate ./asyncapi.yaml @asyncapi/ht
```
## 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'));
+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!');
+ 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) for more examples and full API reference information.
\ No newline at end of file
+See the [API documentation](api) for more examples and full API reference information.
diff --git a/apps/generator/docs/using-private-template.md b/apps/generator/docs/using-private-template.md
index 8d8d9faa9..a2ed2f11b 100644
--- a/apps/generator/docs/using-private-template.md
+++ b/apps/generator/docs/using-private-template.md
@@ -2,40 +2,41 @@
title: "Using private templates"
weight: 180
---
-Generator allows fetching the template from private repositories like Verdaccio, Nexus, npm, etc.
-By default, the generator fetches the template from the public npm registry configured in the npm configuration.
-To fetch the template from a private registry, you need to provide the registry URL and authentication details in the .npmrc. For more information [read the docs](https://docs.npmjs.com/cli/v9/configuring-npm/npmrc).
-However, you can override the default behavior by providing the registry URL and authentication details as arguments of the commandline.
+Generator allows fetching the template from private repositories like Verdaccio, Nexus, npm, etc.
+By default, the generator fetches the template from the public npm registry configured in the npm configuration.
+To fetch the template from a private registry, you need to provide the registry URL and authentication details in the .npmrc. For more information [read the docs](https://docs.npmjs.com/cli/v9/configuring-npm/npmrc).
+However, you can override the default behavior by providing the registry URL and authentication details as arguments of the commandline.
## Private registry using .npmrc:
+
```bash
npm config set registry http://verdaccio:4873
npm config set //verdaccio:4873/:_auth=$(echo -n 'username:password' | base64)
```
-* **npm config set registry** : Provide the registry URL that points to the registry URL.
-* **npm config set _auth** : Provide the base64 encoded value that represents the username and password for basic auth.
-* **npm config set _authToken** : Provide the access token generated by the registry.
+
+- **npm config set registry** : Provide the registry URL that points to the registry URL.
+- **npm config set \_auth** : Provide the base64 encoded value that represents the username and password for basic auth.
+- **npm config set \_authToken** : Provide the access token generated by the registry.
## Private registry overriding arguments:
-* **registry.url**: The URL of the registry where the private template is located. Defaults to `registry.npmjs.org`.
-* **registry.auth**: An optional parameter to pass the npm registry username and password encoded with base64, formatted as `username:password`. For example, if the username and password are `admin` and `nimda`, you need to encode them with the base64 value like `admin:nimda` which results in `YWRtaW46bmltZGE=`.
-* **registry.token**: An optional parameter to pass to the npm registry authentication token. To get the token, you can first authenticate with the registry using `npm login` and then grab the generated token from the `.npmrc` file.
+- **registry.url**: The URL of the registry where the private template is located. Defaults to `registry.npmjs.org`.
+- **registry.auth**: An optional parameter to pass the npm registry username and password encoded with base64, formatted as `username:password`. For example, if the username and password are `admin` and `nimda`, you need to encode them with the base64 value like `admin:nimda` which results in `YWRtaW46bmltZGE=`.
+- **registry.token**: An optional parameter to pass to the npm registry authentication token. To get the token, you can first authenticate with the registry using `npm login` and then grab the generated token from the `.npmrc` file.
## Pulling private template using library:
```javascript
-const generator = new Generator('@asyncapi/html-template', 'output',
- {
- debug: true,
- registry: {
- url: 'http://verdaccio:4873',
- auth: 'YWRtaW46bmltZGE='
- // base64 encoded username and password
- // represented as admin:nimda
-
- }
- });
+const generator = new Generator("@asyncapi/html-template", "output", {
+ debug: true,
+ registry: {
+ url: "http://verdaccio:4873",
+ auth: "YWRtaW46bmltZGE=",
+ // base64 encoded username and password
+ // represented as admin:nimda
+ },
+});
```
+
Assuming you host `@asyncapi/html-template` in a private package registry like Verdaccio. To pull this template, you need to provide `registry.url` option that points to the registry URL and `registry.auth` as a base64 encoded value that represents the username and password. Instead of username and password, you can also pass `registry.token`.
diff --git a/apps/generator/docs/versioning.md b/apps/generator/docs/versioning.md
index 5409d822b..f0c75994a 100644
--- a/apps/generator/docs/versioning.md
+++ b/apps/generator/docs/versioning.md
@@ -3,19 +3,21 @@ 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.
+The generator tool generates whatever you want, as long as it can be defined in a template based on the [AsyncAPI document](asyncapi-document.md). 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 with all its dependencies, like AsyncAPI Generator; `asyncapi config versions`
+> Use the following command to check the version of the AsyncAPI CLI you have installed with all its dependencies, like AsyncAPI Generator; `asyncapi config versions`
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
@@ -28,4 +30,4 @@ 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.
\ No newline at end of file
+> 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.