From 82560318e6bcefa265b904eb44209cca31cc9a0b Mon Sep 17 00:00:00 2001 From: Florence Njeri <40742916+Florence-Njeri@users.noreply.github.com> Date: Thu, 25 Jan 2024 10:50:28 +0300 Subject: [PATCH] docs: create the model generation guide (#1096) --- .github/workflows/update-docs-in-website.yml | 1 + docs/index.md | 3 + docs/installation-guide.md | 2 +- docs/model-generation.md | 84 ++++++++++++++++++++ docs/template-development.md | 4 +- docs/template.md | 2 +- docs/usage.md | 6 +- 7 files changed, 96 insertions(+), 6 deletions(-) create mode 100644 docs/model-generation.md diff --git a/.github/workflows/update-docs-in-website.yml b/.github/workflows/update-docs-in-website.yml index 3ceb7dc84..3f828b9f3 100644 --- a/.github/workflows/update-docs-in-website.yml +++ b/.github/workflows/update-docs-in-website.yml @@ -35,6 +35,7 @@ jobs: - name: Copy generator folder from Current Repo to Another working-directory: ./website run: | + rm -r ./pages/docs/tools/generator mkdir -p ./pages/docs/tools/generator rm ../generator/docs/README.md rm -r ../generator/docs/jsdoc2md-handlebars diff --git a/docs/index.md b/docs/index.md index c8d2ca260..0c32dbd82 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,6 +5,9 @@ weight: 10 The AsyncAPI generator is a tool that generates anything you want using the **[AsyncAPI Document](generator/asyncapi-document)** and **[Template](generator/template)** that are supplied as inputs to the AsyncAPI CLI. The generator was built with extensibility in mind; you can use the generator to generate anything you want, provided that it can be defined in a template, such as code, diagrams, markdown files, microservices, and applications. A number of [community-maintained templates](https://github.com/search?q=topic%3Aasyncapi+topic%3Agenerator+topic%3Atemplate) are now available for immediate usage. +> **Note:** +> If your primary objective is to generate models/classes for your event-driven architecture apps, use [AsyncAPI Modelina](/docs/tools/generator/model-generation), which is supported in the AsyncAPI CLI, instead of using the AsyncAPI Generator. Modelina is specifically designed for model generation and provides utilities for working with the AsyncAPI document. + ### Generator use cases - Generation of interactive and understandable API documentation - Generation of APIs' client libraries diff --git a/docs/installation-guide.md b/docs/installation-guide.md index 69e81b53f..9db49b21d 100644 --- a/docs/installation-guide.md +++ b/docs/installation-guide.md @@ -53,7 +53,7 @@ You can install in Linux by using `dpkg`, a package manager for debian: For further installation instructions for different operating systems, read the [AsyncAPI CLI documentation](https://github.com/asyncapi/cli#installation). > **Remember:** -> Each [community-developed template](https://github.com/search?q=topic%3Aasyncapi+topic%3Agenerator+topic%3Atemplate) is dependent on a certain version of the generator for it to work correctly. Before you install the generator CLI, check the template's `package.json` for the version of the generator CLI your template is compatible with. Read the [versioning docs](versioning) to learn why it's important to use certain generator versions with your templates. +> Each [community-developed template](https://github.com/search?q=topic%3Aasyncapi+topic%3Agenerator+topic%3Atemplate) is dependent on a certain version of the generator for it to work correctly. Before you install the AsyncAPI CLI, check the template's `package.json` for the version of the AsyncAPI CLI your template is compatible with. Read the [versioning docs](versioning) to learn why it's important to use certain generator versions with your templates. ### Update AsyncAPI CLI There are several reasons why you might want to update your generator version: diff --git a/docs/model-generation.md b/docs/model-generation.md new file mode 100644 index 000000000..f15ea8d24 --- /dev/null +++ b/docs/model-generation.md @@ -0,0 +1,84 @@ +--- +title: "Adding models generation in template" +weight: 200 +--- + +This guide will walk you through the process of enabling models/types generation in a template by using [Modelina](https://www.asyncapi.com/tools/modelina). + +Modelina is an AsyncAPI library designed for generating data models using inputs such as [AsyncAPI](generator/asyncapi-document), OpenAPI, or JSON schema inputs. Its functionality revolves around creating data models from the provided AsyncAPI document and the model template, which defines message payloads. It is better to use Modelina in your template to handle model generation rather than providing custom templates. + +You can integrate the work shown in this guide into a template by following the [tutorial about creating a template](https://www.asyncapi.com/docs/tools/generator/generator-template). + +In this guide, you'll learn how to use Modelina in a template code to enable support for Python data model generation. + +## Add Modelina dependency + +Install Modelina in your project using npm: `npm install --save @asyncapi/modelina`. + +Ensure your template's `package.json` file now contains Modelina pointing to its latest version: + + ```json + "dependencies": { + // ... + "@asyncapi/modelina": "^2.0.5" + // ... + } +``` + +## Create a models.js file + +Create a new directory in the **template** directory named **src/models** and create a **models.js** file within it. In the **models.js** file, add the following code: + +```python +// 1 +import { File } from '@asyncapi/generator-react-sdk'; +// 2 +import { PythonGenerator, FormatHelpers } from '@asyncapi/modelina'; + +/** + * @typedef RenderArgument + * @type {object} + * @property {AsyncAPIDocument} asyncapi document object received from the generator. + */ + +/** + * Render all schema models + * @param {RenderArgument} param0 + * @returns + */ +// 3 +export default async function schemaRender({ asyncapi }) { + // 4 + const pythonGenerator = new PythonGenerator(); + // 5 + const models = await pythonGenerator.generate(asyncapi); + // 6 + const files = []; + // 7 + for (const model of models) { + // 8 + const modelFileName = `${FormatHelpers.toPascalCase(model.modelName)}.py`; + // 9 + files.push({model.result}); + } + return files; +} +``` + +Let's break it down. The code snippet above does the following: + +1. The `File` component from the [generator react SDK](https://github.com/asyncapi/generator-react-sdk) is needed to handle the further rendering of generated models into files. +2. The `PythonGenerator` generator is the core needed for model generation. Additionally, you can import [FormatHelpers](https://github.com/asyncapi/modelina/blob/master/src/helpers/FormatHelpers.ts) that provides a set of helpers making it easier to modify model names to match your required case. +3. You can change the name `schemaRender` to anything else like `modelRenderer`. More importantly, this must be an `async` function and a default export. This function is invoked during generation process and should contain the logic behind models generation. +4. First, create an instance of the `PythonGenerator` model generator. If you decide to use present functionality from Modelina, you need to pass your presets here during instance creation. +5. The actual model generation is one line of code, and as a result you get an array of models that later you need to turn into files. +6. You need to define an array that must be returned from `schemaRender` function. The array must contain React components, and in this case, the `` component. +7. Iterate over generated models and use their content to create proper definitions of `` components. +8. Notice how using Modelina helpers, in this case the `toPascalCase` function, let's you make sure that the filename of your model follows specific case pattern. +9. Each component must be added into the `files` array that you later return from the default function. Notice the definition of the `` 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. + +## Conclusion + +Modelina provides a flexible and powerful way to generate data models from AsyncAPI, OpenAPI, or JSON Schema documents. By integrating Modelina you can much faster enable models generation in your template. diff --git a/docs/template-development.md b/docs/template-development.md index 35af42ce4..1c9536c9d 100644 --- a/docs/template-development.md +++ b/docs/template-development.md @@ -2,6 +2,8 @@ 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. ## Minimum template requirements @@ -130,7 +132,7 @@ Newer: Version is: **{params.version || asyncapi.info.version()}** ``` -Now that you have added all the configuration options, you can start the generation process using the generator CLI. You can pass these parameters via the CLI: `--param name=value or -p name=value`. +Now that you have added all the configuration options, you can start the generation process using the AsyncAPI CLI. You can pass these parameters via the CLI: `--param name=value or -p name=value`. The above configuration helps template users override the existing version with a new version on the command line. (Example: `-p version=2.0.0`) ## Hooks diff --git a/docs/template.md b/docs/template.md index 6d0e9d27e..bccacad7d 100644 --- a/docs/template.md +++ b/docs/template.md @@ -24,7 +24,7 @@ You can store template projects on a local drive or as a `git` repository during 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 generator 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. diff --git a/docs/usage.md b/docs/usage.md index 6b6e7aa15..88d35b16c 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -4,10 +4,10 @@ weight: 30 --- There are two ways to use the generator: -- [Generator CLI](#generator-cli) +- [AsyncAPI CLI](#generator-cli) - [Generator library](#using-as-a-modulepackage) -## Generator CLI +## AsyncAPI CLI ```bash Usage: asyncapi generate fromTemplate