diff --git a/markdown/docs/tools/generator/configuration-file.md b/markdown/docs/tools/generator/configuration-file.md index 0f37a3e921f..c11cfd00e19 100644 --- a/markdown/docs/tools/generator/configuration-file.md +++ b/markdown/docs/tools/generator/configuration-file.md @@ -60,8 +60,8 @@ The `generator` property from `package.json` file must contain a JSON object tha "lib/lib/config.js" ], "generator": "<2.0.0", - "filters": [ - "@asyncapi/generator-filters" + "filters":[ + "my-package-with-filters" ], "hooks": { "@asyncapi/generator-hooks": "hookFunctionName" diff --git a/markdown/docs/tools/generator/file-templates.md b/markdown/docs/tools/generator/file-templates.md index 5ba4a9687d3..7a7a8ce77c4 100644 --- a/markdown/docs/tools/generator/file-templates.md +++ b/markdown/docs/tools/generator/file-templates.md @@ -3,7 +3,11 @@ title: "File templates" weight: 140 --- -It is possible to generate files for each specific object in your AsyncAPI documentation. For example, you can specify a filename like `$$channel$$.js` to generate a file for each channel defined in your AsyncAPI. The following file-template names and extra variables in them are available: +## Generating files with the Nunjucks render engine + +> **Note**: This section applies only to the Nunjucks render engine. For information on using the React render engine, refer to the [Generating files with the React render engine](#generating-files-with-the-react-render-engine) section below. + +It is possible to generate files for each specific object in your AsyncAPI documentation using the Nunjucks render engine. For example, you can specify a filename like `$$channel$$.js` to generate a file for each channel defined in your AsyncAPI. The following file-template names and extra variables are available: - `$$channel$$`, within the template-file you have access to two variables [`channel`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channel) and [`channelName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channels). Where the `channel` contains the current channel being rendered. - `$$message$$`, within the template-file you have access to two variables [`message`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message) and [`messageName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message). Where `message` contains the current message being rendered. @@ -25,7 +29,7 @@ Schema name is '{{schemaName}}' and properties are: {% endfor %} ``` -With following AsyncAPI: +With the following AsyncAPI: ``` components: schemas: @@ -53,15 +57,82 @@ Schema name is 'people' and properties are: - id ``` -### React +> You can see an example of a file template that uses the Nunjucks render engine [here](https://github.com/asyncapi/template-for-generator-templates/tree/nunjucks/template/schemas). + +## Generating files with the React render engine -The above way of rendering **file templates** works for both `nunjucks` and `react` render engines, but `react` also has another, more generic way to render multiple files. It is enough to return an array of `File` components in the rendering component. See the following example: +The above method of rendering **file templates** only works for the Nunjucks render engine. To use the React render engine, you need to follow a different approach. The React render engine allows for a more generic way to render multiple files by returning an array of `File` components in the rendering component. This can be particularly useful for complex templates or when you need to generate a large number of files with varying content. + +### Example 1: Rendering hardcoded files + +The following is a simple hardcoded example of how to render multiple files using the React render engine: ```tsx +import { File} from "@asyncapi/generator-react-sdk"; + export default function({ asyncapi }) { return [ Content, Content ] } -``` \ No newline at end of file +``` + +### Example 2: Rendering files based on the AsyncAPI Schema + +In practice, to render the multiple files, that are generated from the data defined in your AsyncAPI, you'll iterate over the array of schemas and generate a file for each schema as shown in the example below: + +```js +import { File} from "@asyncapi/generator-react-sdk"; + +/* + * To render multiple files, it is enough to return an array of `File` components in the rendering component, like in following example. + */ +export default function({ asyncapi }) { + const schemas = asyncapi.allSchemas(); + const files = []; + // schemas is an instance of the Map + schemas.forEach((schema) => { + + files.push( + // We return a react file component and each time we do it, the name of the generated file will be a schema name + // Content of the file will be a variable representing schema + + const { schema.id() } = { JSON.stringify(schema._json, null, 2) } + + ); + }); + return files; +} +``` + +### Example 3: Rendering files for each channel + +Additionally, you can generate multiple files for each channel defined in your AsyncAPI specification using the React render engine as shown in the example below: + +```js +import { File, Text } from "@asyncapi/generator-react-sdk"; + + +export default function ({ asyncapi }) { + const files = []; + + // Generate files for channels + asyncapi.channels().forEach((channel) => { + const channelName = channel.id(); + + files.push( + + # Channel: {channelName} + + {channel.hasDescription() && `${channel.description()}`} + + + ); + }); + return files; +} +``` +The code snippet above uses the `Text` component to write file content to the `.md` markdown file. The `newline` property is used to ensure that the content isn't all rendered in one line in the markdown file. In summary, the code snippet above is a practical guide on generating properly formatted multiline Markdown files for each channel in an AsyncAPI document. + +> You can see an example of a file template that uses the React render engine [here](https://github.com/asyncapi/template-for-generator-templates/blob/master/template/schemas/schema.js). diff --git a/markdown/docs/tools/generator/generator-template.md b/markdown/docs/tools/generator/generator-template.md index be84e45876d..e9643234e74 100644 --- a/markdown/docs/tools/generator/generator-template.md +++ b/markdown/docs/tools/generator/generator-template.md @@ -159,7 +159,7 @@ To see this in action, navigate to the **python-mqtt-client-template** directory ``` cmd Generation in progress. Keep calm and wait a bit... done -Check out your shiny new generated files at output. +Check out your shiny new generated files at test/project. ``` Navigating to the **test/project** directory. You should see a **client.py** file; the only content is `Temperature Service`. diff --git a/markdown/docs/tools/generator/nunjucks-render-engine.md b/markdown/docs/tools/generator/nunjucks-render-engine.md index a64b64ab896..34626b49b91 100644 --- a/markdown/docs/tools/generator/nunjucks-render-engine.md +++ b/markdown/docs/tools/generator/nunjucks-render-engine.md @@ -73,6 +73,7 @@ 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. You can also use the official AsyncAPI [filters library](https://github.com/asyncapi/generator-filters). To learn how to add such filters to configuration [read more about the configuration file](#configuration-file). +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 diff --git a/markdown/docs/tools/generator/template.md b/markdown/docs/tools/generator/template.md index f955a60f3e6..b8f31db016f 100644 --- a/markdown/docs/tools/generator/template.md +++ b/markdown/docs/tools/generator/template.md @@ -65,7 +65,7 @@ Template Name | Description | Source code `@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.