From 547b02f82e5326da98098b5bbd662256e72f8a8d Mon Sep 17 00:00:00 2001 From: f-njeri Date: Sat, 20 Jul 2024 13:46:02 +0300 Subject: [PATCH 1/8] first draft adding the React render engine section --- apps/generator/docs/file-templates.md | 40 ++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/apps/generator/docs/file-templates.md b/apps/generator/docs/file-templates.md index 5ba4a9687..f27ede037 100644 --- a/apps/generator/docs/file-templates.md +++ b/apps/generator/docs/file-templates.md @@ -3,7 +3,10 @@ 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 nun-jucks render engine + +> **Note**: This section applies only to the Nunjucks render engine. For information on using the React render engine, refer to the 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 in them 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. @@ -53,9 +56,15 @@ 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 nun-jucks render engine + +The above way of rendering **file templates** only works for the Nunjucks render engines. 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. -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: +### Example + +The following is a simple hardcoded way to render multiple files using the React render engine: ```tsx export default function({ asyncapi }) { @@ -64,4 +73,27 @@ export default function({ asyncapi }) { Content ] } -``` \ No newline at end of file +``` + +In real life, to render multiple files, you'll iterate over the array of files as shown in the example below: + +```js +/* + * 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(); + // schemas is an instance of the Map + return Array.from(schemas).map(([schemaName, schema]) => { + return ( + // 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 single schema definition + {schema} + + ); + }); +} +``` + +> 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). \ No newline at end of file From 316286120b273f20e1f423bb80e36e87a9cd47e0 Mon Sep 17 00:00:00 2001 From: f-njeri Date: Tue, 23 Jul 2024 10:44:22 +0300 Subject: [PATCH 2/8] final editorial --- apps/generator/docs/file-templates.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/apps/generator/docs/file-templates.md b/apps/generator/docs/file-templates.md index f27ede037..982bf2cec 100644 --- a/apps/generator/docs/file-templates.md +++ b/apps/generator/docs/file-templates.md @@ -3,10 +3,11 @@ title: "File templates" weight: 140 --- -## Generating files with nun-jucks render engine +## 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 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 in them are available: +> **Note**: This section applies only to the Nunjucks render engine. For information on using the React render engine, refer to the 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. @@ -28,7 +29,7 @@ Schema name is '{{schemaName}}' and properties are: {% endfor %} ``` -With following AsyncAPI: +With the following AsyncAPI: ``` components: schemas: @@ -56,15 +57,15 @@ Schema name is 'people' and properties are: - id ``` -> 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) +> 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 nun-jucks render engine +## Generating files with the React render engine -The above way of rendering **file templates** only works for the Nunjucks render engines. 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. +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 -The following is a simple hardcoded way to render multiple files using the React render engine: +The following is a simple hardcoded example of how to render multiple files using the React render engine: ```tsx export default function({ asyncapi }) { @@ -75,7 +76,7 @@ export default function({ asyncapi }) { } ``` -In real life, to render multiple files, you'll iterate over the array of files as shown in the example below: +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 /* From e0c787482c86aa0b4299366bc5c0d19265dde2c1 Mon Sep 17 00:00:00 2001 From: f-njeri Date: Wed, 24 Jul 2024 12:49:12 +0300 Subject: [PATCH 3/8] fix typo --- apps/generator/docs/file-templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/generator/docs/file-templates.md b/apps/generator/docs/file-templates.md index 982bf2cec..ab1b6dffd 100644 --- a/apps/generator/docs/file-templates.md +++ b/apps/generator/docs/file-templates.md @@ -5,7 +5,7 @@ weight: 140 ## 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 refer to the [Generating files with the React render engine](#generating-files-with-the-react-render-engine) section below. +> **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: From 4265c60c2780b9eecec84ba92e585535113026ae Mon Sep 17 00:00:00 2001 From: f-njeri Date: Mon, 19 Aug 2024 08:06:29 +0300 Subject: [PATCH 4/8] add channels example --- apps/generator/docs/file-templates.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/apps/generator/docs/file-templates.md b/apps/generator/docs/file-templates.md index ab1b6dffd..5cec2cef6 100644 --- a/apps/generator/docs/file-templates.md +++ b/apps/generator/docs/file-templates.md @@ -97,4 +97,31 @@ export default function({ asyncapi }) { } ``` +Additionally, you can generate files for each channel defined in your AsyncAPI specification using the React render engine as shown in the example below: + +```js +import { File } from '@asyncapi/generator-react-sdk'; + +export default function({ asyncapi }) { + const files = []; + + // Generate files for channels + asyncapi.channels().forEach((channel, channelName) => { + files.push( + + # Channel: {channelName} + + Description: {channel.description() || 'No description provided'} + + ## Operations + {channel.publish() &&
Publish: {channel.publish().summary()}
} + {channel.subscribe() &&
Subscribe: {channel.subscribe().summary()}
} + + ); + }); + + return files; +} +``` + > 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). \ No newline at end of file From 452d0fd8959a56b9d40f9b7e5f0b8872c24d7ab0 Mon Sep 17 00:00:00 2001 From: f-njeri Date: Mon, 19 Aug 2024 08:13:27 +0300 Subject: [PATCH 5/8] edit react render engine section --- apps/generator/docs/file-templates.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/apps/generator/docs/file-templates.md b/apps/generator/docs/file-templates.md index 5cec2cef6..8ad1c8ddf 100644 --- a/apps/generator/docs/file-templates.md +++ b/apps/generator/docs/file-templates.md @@ -63,7 +63,7 @@ Schema name is 'people' and properties are: 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 +### Example 1: Rendering hardcoded files The following is a simple hardcoded example of how to render multiple files using the React render engine: @@ -76,6 +76,8 @@ export default function({ asyncapi }) { } ``` +### 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 @@ -97,6 +99,8 @@ export default function({ asyncapi }) { } ``` +### Example 3: Rendering files for each channel + Additionally, you can generate files for each channel defined in your AsyncAPI specification using the React render engine as shown in the example below: ```js From 9a8a784d742bfdbb0d89a0264311d49fdbcf18a1 Mon Sep 17 00:00:00 2001 From: f-njeri Date: Wed, 28 Aug 2024 07:27:46 +0300 Subject: [PATCH 6/8] fix invalid file generation example --- apps/generator/docs/file-templates.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/apps/generator/docs/file-templates.md b/apps/generator/docs/file-templates.md index 8ad1c8ddf..d25e9d1a5 100644 --- a/apps/generator/docs/file-templates.md +++ b/apps/generator/docs/file-templates.md @@ -101,31 +101,30 @@ export default function({ asyncapi }) { ### Example 3: Rendering files for each channel -Additionally, you can generate files for each channel defined in your AsyncAPI specification using the React render engine as shown in the example below: +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 } from '@asyncapi/generator-react-sdk'; +import { File, Text } from "@asyncapi/generator-react-sdk"; -export default function({ asyncapi }) { +export default function ({ asyncapi }) { const files = []; // Generate files for channels - asyncapi.channels().forEach((channel, channelName) => { - files.push( - - # Channel: {channelName} - - Description: {channel.description() || 'No description provided'} + asyncapi.channels().forEach((channel) => { + const channelName = channel.id(); - ## Operations - {channel.publish() &&
Publish: {channel.publish().summary()}
} - {channel.subscribe() &&
Subscribe: {channel.subscribe().summary()}
} + 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). \ No newline at end of file From 85528df12eff2e8569e17db887dcf9170fb098a3 Mon Sep 17 00:00:00 2001 From: f-njeri Date: Fri, 30 Aug 2024 08:10:43 +0300 Subject: [PATCH 7/8] doc fixes --- apps/generator/docs/file-templates.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/apps/generator/docs/file-templates.md b/apps/generator/docs/file-templates.md index d25e9d1a5..17c0bc5b4 100644 --- a/apps/generator/docs/file-templates.md +++ b/apps/generator/docs/file-templates.md @@ -68,6 +68,8 @@ The above method of rendering **file templates** only works for the Nunjucks ren 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, @@ -81,14 +83,17 @@ export default function({ asyncapi }) { 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 - return Array.from(schemas).map(([schemaName, schema]) => { - return ( + schemas.forEach((schema, schemaName) => { + 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 single schema definition @@ -96,6 +101,7 @@ export default function({ asyncapi }) { ); }); + return files; } ``` @@ -106,6 +112,7 @@ Additionally, you can generate multiple files for each channel defined in your A ```js import { File, Text } from "@asyncapi/generator-react-sdk"; + export default function ({ asyncapi }) { const files = []; From 8ef5496be4fd9a5bf8d5e24c4ce812a697479074 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Mon, 2 Sep 2024 11:24:27 +0200 Subject: [PATCH 8/8] Update file-templates.md --- apps/generator/docs/file-templates.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/apps/generator/docs/file-templates.md b/apps/generator/docs/file-templates.md index 17c0bc5b4..7a7a8ce77 100644 --- a/apps/generator/docs/file-templates.md +++ b/apps/generator/docs/file-templates.md @@ -92,12 +92,13 @@ export default function({ asyncapi }) { const schemas = asyncapi.allSchemas(); const files = []; // schemas is an instance of the Map - schemas.forEach((schema, schemaName) => { + 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 single schema definition - {schema} + // Content of the file will be a variable representing schema + + const { schema.id() } = { JSON.stringify(schema._json, null, 2) } ); }); @@ -134,4 +135,4 @@ export default function ({ asyncapi }) { ``` 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). \ No newline at end of file +> 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).