diff --git a/apps/generator/docs/file-templates.md b/apps/generator/docs/file-templates.md index 5ba4a9687..7a7a8ce77 100644 --- a/apps/generator/docs/file-templates.md +++ b/apps/generator/docs/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).