docs: create the model generation guide

[Florence-Njeri]

Description

• New guide explaining how to go about generating types using Modelina
• In the introduction and the template development docs, I've added a note stating that if someone is only interested in types/model generation, they should use Modelina directly.
• Updated CLI naming

Related issue(s)
Resolves #1042

[derberg]

You will need to adjust narrative in the main document as the scope of #1042 was not a tutorial, but more of a guide that tells you what is needed and shows an example.

• we do not need to mention https://github.com/derberg/python-mqtt-client-template. You can just add a note that the example you provide can be integrated in a template that one can create by following https://www.asyncapi.com/docs/tools/generator/generator-template
• I think it is enough that first step of the guide just says that @asyncapi/modelina needs to be added to template dependencies as npm install --save @asyncapi/modelina because then it is automatically added to package.json
• Model generation using the AsyncAPI CLI section can be removed as it is not adding anything new, template with or without modelina - generation is always the same. You can just link to https://www.asyncapi.com/docs/tools/generator/usage#generator-cli (btw we have error there as section should be called AsyncAPI CLI, and we should also have a link to https://www.asyncapi.com/docs/tools/cli there)
• please remember about proper linking inside asyncapi.com with relative links and also consistent usage of upper/lower cases with names of tools

also, in your PR can you add between line 37 and 38 in https://github.com/asyncapi/generator/blob/master/.github/workflows/update-docs-in-website.yml#L37-L38 a line rm -r ./pages/docs/tools/generator to always have a clean and empty state of generator docs folder in website? Problem is that we now do not remove, and just add, so when we rename files like this https://github.com/asyncapi/generator/blob/master/docs/generator-template.md then we now get a duplicated tutorial in website

[Florence-Njeri]

You will need to adjust narrative in the main document as the scope of #1042 was not a tutorial, but more of a guide that tells you what is needed and shows an example.

• we do not need to mention https://github.com/derberg/python-mqtt-client-template. You can just add a note that the example you provide can be integrated in a template that one can create by following https://www.asyncapi.com/docs/tools/generator/generator-template
• I think it is enough that first step of the guide just says that @asyncapi/modelina needs to be added to template dependencies as npm install --save @asyncapi/modelina because then it is automatically added to package.json
• Model generation using the AsyncAPI CLI section can be removed as it is not adding anything new, template with or without modelina - generation is always the same. You can just link to https://www.asyncapi.com/docs/tools/generator/usage#generator-cli (btw we have error there as section should be called AsyncAPI CLI, and we should also have a link to https://www.asyncapi.com/docs/tools/cli there)
• please remember about proper linking inside asyncapi.com with relative links and also consistent usage of upper/lower cases with names of tools

also, in your PR can you add between line 37 and 38 in https://github.com/asyncapi/generator/blob/master/.github/workflows/update-docs-in-website.yml#L37-L38 a line rm -r ./pages/docs/tools/generator to always have a clean and empty state of generator docs folder in website? Problem is that we now do not remove, and just add, so when we rename files like this https://github.com/asyncapi/generator/blob/master/docs/generator-template.md then we now get a duplicated tutorial in website

Hey @derberg, I have addressed all the feedback you left on this PR

[Florence-Njeri]

@derberg this is ready for a second review

[derberg]

left one big comment

please also update the title and description of PR - we do not merge tutorial with this PR

[Florence-Njeri]

Review from Lukasz

[derberg]

@Florence-Njeri please have a look at this comment with big modification - there was suppose to be much more content, not just finish with adding dependency 🤔

also do not forget about 👇🏼

please also update the title and description of PR - we do not merge tutorial with this PR

[derberg]

sorry @Florence-Njeri my comment was weirdly interpreted by GitHub commit suggestion

pasting the same comment below:

---

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.

Modelina is an AsyncAPI library designed for generating data models by utilizing inputs like AsyncAPI, 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 work shown in this guide in a template that you can create by following tutorial about creating a template.

In this guide, you'll learn how to use Modelina in a template code to enable support for Python data models generation.

Add Modelina dependency

Install Modelina in your project using npm: npm install --save @asyncapi/modelina.

Your template's package.json file should now contain Modelina pointing to its latest version:

"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:

// 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(<File name={modelFileName}>{model.result}</File>);
  }
  return files;
}

Let's break it down. The code snippet above does the following:

1. The File component from the generator react SDK is needed to handle further rendering of generated models into files.
2. The PythonGenerator generator is a core that you need for models generation. Additionally you can import FormatHelpers that give you a set of helpers that make it easier to modify model names to match your required case.
3. You can change the name schemaRender to anything else like modelRenderer. More important is that this must be an async function and be a default export. This function is invoked during generation process and it should contain the logic behind models generation.
4. First you 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. Actual models 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 <File> component.
7. Iterate over generated models and use their content to create proper definitions of <File> component.
8. Notice how using Modelina helpers, in this case toPascalCase function, you can make sure that the filename of your model follows specific case pattern.
9. Each component must be added to files array that you later return from the default function. Notice the definition of <File> 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 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.

suggested restructure and rewrite that I did:

• give more details
• follow guide not tutorial
• remove CLI as in this topic CLI is not relevant, especially that Generator can also be used as library and not only as tool integrated in AsyncAPI CLI

@Florence-Njeri I suck at grammar, so please after accepting the change, do a review and probably improvement

[asyncapi-bot]

Hello, @derberg! 👋🏼

    I'm 🧞🧞🧞 Genie 🧞🧞🧞 from the magic lamp. Looks like somebody needs a hand!

    At the moment the following comments are supported in pull requests:

    - `/ready-to-merge` or `/rtm` - This comment will trigger automerge of PR in case all required checks are green, approvals in place and do-not-merge label is not added
    - `/do-not-merge` or `/dnm` - This comment will block automerging even if all conditions are met and ready-to-merge label is added
    - `/autoupdate` or `/au` - This comment will add `autoupdate` label to the PR and keeps your PR up-to-date to the target branch's future changes. Unless there is a merge conflict or it is a draft PR.

[sonarqubecloud]

Quality Gate passed

Kudos, no new issues were introduced!

0 New issues
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarCloud

[derberg]

@jonaslagoni @kennethaasan @magicmatatjahu since this is Modelina related, anything from your side? is it a good way to promote Modelina as component that enables models generation in app template?

maybe long term would be better to have a dedicated React component that makes it even easier to embed model generation - but for now I think it should be enough, especially that there is nothing else at the moment

[jonaslagoni]

LGTM 👍

[derberg]

/rtm

[asyncapi-bot]

🎉 This PR is included in version 1.17.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀