From 542889e6a4af1f747ce10af4f3ebb7d3e10d4159 Mon Sep 17 00:00:00 2001 From: Florence-Njeri Date: Wed, 20 Jul 2022 11:26:33 +0300 Subject: [PATCH 01/10] add asyncapiDocument and asyncapiString documentation --- docs/asyncapi-file.md | 85 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 84 insertions(+), 1 deletion(-) diff --git a/docs/asyncapi-file.md b/docs/asyncapi-file.md index d8c6dff45..b3f6ec625 100644 --- a/docs/asyncapi-file.md +++ b/docs/asyncapi-file.md @@ -3,4 +3,87 @@ title: "AsyncAPI Specification File" weight: 20 --- ->This document is under construction. \ No newline at end of file +### What is the Asyncapi Specification? +The **AsyncAPI specification** defines a standard, protocol-agnostic interface description of message-based or event-driven APIs which allows the people or machines communicating with one another to understand the capabilities of an event-driven API without requiring access to the source code, documentation or inspecting the network traffic. + +This specification file when fed as an input to the generator library using the **asyncAPI CLI command**, shown in the code snippet below, generates API documentation or API code with it. + +```bash +ag asyncapi.yaml ~/my-template +``` +1. **ag** is the asyncAPI generator +2. **asyncapi.yaml** is the specification file +3. **~/my-template** is the template you are using + +### Use cases of of the API definition file +- Interactive documentation +- Code generation +- Validation of messages the client receives +- Application of API management policies to messages before they arive to the broker + + + +If you are looking to learn how to create your own asyncapi specification file or you need to refresh your knowledge,check out our official [documentation](https://www.asyncapi.com/docs/reference/specification/v2.4.0) + + +In this documentation you'll learn about the inner working of the generator and what happens once the spec file is fed to the generator and how you can use the content of spec file using the asyncAPI document in your code. + + + +The generator receives the template and AsyncAPI specification file as an input. The illustration below clearly depicts the whole proccess from when you add the template and your specification file to the cli tool, to how the generator uses the input to generate the output you need. + +``` mermaid +graph LR + E[ Specification File ] -->| asyncapi specification | B(Generator) + F[ Generator Template ] -->| Template | B{Generator} + B -->| asyncapi String| C[Parser] + C -->|One| D[asyncapi Document] +``` +The generator library upon receiving as an input the specificication file and then generates code with it. As a user you will need access to the data that was defined in the specification file. +When you are writing your template, you get access to the specification file in two different forms; the originalAsyncApi which is a stringified version of the specification `.yml` file and the second is the asyncapiDocument + + +#### Method 1: asyncapiString + template ## +The **asynapiString** is a stringified version of your specification yaml that your template gets access to using the templates hook `createAsyncapiFile(generator)`. The template then gets the original specification file by calling `generator.originalAsyncAPI` which returns a stringified version of the original spec file. You can therefore use it in your generatoed application code. +Example: +``` +const asyncapiString = ` +asyncapi: 2.0.0 +info: + title: Example to show stringified specification file + version: 0.1.0 +channels: + example: + publish: + message: + schemaFormat: 'application/vnd.oai.openapi;version=3.0.0' + payload: # The following is an OpenAPI schema + type: object + properties: + title: + type: string + nullable: true + author: + type: string + example: Jack Johnson +` +``` + + + +#### Method 2: asyncapiDocument+ template ## +Once the specification yml or json is passed as an input to the generator library, it is passed on to the Parser library which then manipulates the file to a more structured document called the [asyncapiDocument](https://github.com/asyncapi/parser-js/blob/master/API.md#module_@asyncapi/parser+AsyncAPIDocument). It should be used to access the documents content for example, to extract the version of the spec file used for your Readme.md, you can do that using the asyncapiDocument by running `asyncapiDocument.version` or to get the message payload using `asyncapiDocument.allMessages` + + + +Note: How it simplifies the structure of the spec file which is complex and nested + +Note 2: Mention how you can check to see how these 2 docs are used in the written templates e.g node.js template +Note 3: https://github.com/asyncapi/template-for-generator-templates#template-context +Note 4: Both files are passed to the renderer engines ie React ans nunjucks +Note 5: You get access to these 2 files in the templates you will use +Note 6: Adv of one over the other +Note 7: Link to the parser docs or talk about the parser +Note 8: Show the structure of the asyncapiDocument as a code snippet +Note 9: Listen to the last section of the recording again \ No newline at end of file From 395db7468871788fe2d5126d35e9ffc64a3ceab3 Mon Sep 17 00:00:00 2001 From: Florence-Njeri Date: Tue, 15 Nov 2022 09:12:54 +0300 Subject: [PATCH 02/10] delete stale async-api file --- docs/asyncapi-file.md | 89 ------------------------------------------- 1 file changed, 89 deletions(-) delete mode 100644 docs/asyncapi-file.md diff --git a/docs/asyncapi-file.md b/docs/asyncapi-file.md deleted file mode 100644 index b3f6ec625..000000000 --- a/docs/asyncapi-file.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: "AsyncAPI Specification File" -weight: 20 ---- - -### What is the Asyncapi Specification? -The **AsyncAPI specification** defines a standard, protocol-agnostic interface description of message-based or event-driven APIs which allows the people or machines communicating with one another to understand the capabilities of an event-driven API without requiring access to the source code, documentation or inspecting the network traffic. - -This specification file when fed as an input to the generator library using the **asyncAPI CLI command**, shown in the code snippet below, generates API documentation or API code with it. - -```bash -ag asyncapi.yaml ~/my-template -``` -1. **ag** is the asyncAPI generator -2. **asyncapi.yaml** is the specification file -3. **~/my-template** is the template you are using - -### Use cases of of the API definition file -- Interactive documentation -- Code generation -- Validation of messages the client receives -- Application of API management policies to messages before they arive to the broker - - - -If you are looking to learn how to create your own asyncapi specification file or you need to refresh your knowledge,check out our official [documentation](https://www.asyncapi.com/docs/reference/specification/v2.4.0) - - -In this documentation you'll learn about the inner working of the generator and what happens once the spec file is fed to the generator and how you can use the content of spec file using the asyncAPI document in your code. - - - -The generator receives the template and AsyncAPI specification file as an input. The illustration below clearly depicts the whole proccess from when you add the template and your specification file to the cli tool, to how the generator uses the input to generate the output you need. - -``` mermaid -graph LR - E[ Specification File ] -->| asyncapi specification | B(Generator) - F[ Generator Template ] -->| Template | B{Generator} - B -->| asyncapi String| C[Parser] - C -->|One| D[asyncapi Document] -``` -The generator library upon receiving as an input the specificication file and then generates code with it. As a user you will need access to the data that was defined in the specification file. -When you are writing your template, you get access to the specification file in two different forms; the originalAsyncApi which is a stringified version of the specification `.yml` file and the second is the asyncapiDocument - - -#### Method 1: asyncapiString + template ## -The **asynapiString** is a stringified version of your specification yaml that your template gets access to using the templates hook `createAsyncapiFile(generator)`. The template then gets the original specification file by calling `generator.originalAsyncAPI` which returns a stringified version of the original spec file. You can therefore use it in your generatoed application code. -Example: -``` -const asyncapiString = ` -asyncapi: 2.0.0 -info: - title: Example to show stringified specification file - version: 0.1.0 -channels: - example: - publish: - message: - schemaFormat: 'application/vnd.oai.openapi;version=3.0.0' - payload: # The following is an OpenAPI schema - type: object - properties: - title: - type: string - nullable: true - author: - type: string - example: Jack Johnson -` -``` - - - -#### Method 2: asyncapiDocument+ template ## -Once the specification yml or json is passed as an input to the generator library, it is passed on to the Parser library which then manipulates the file to a more structured document called the [asyncapiDocument](https://github.com/asyncapi/parser-js/blob/master/API.md#module_@asyncapi/parser+AsyncAPIDocument). It should be used to access the documents content for example, to extract the version of the spec file used for your Readme.md, you can do that using the asyncapiDocument by running `asyncapiDocument.version` or to get the message payload using `asyncapiDocument.allMessages` - - - -Note: How it simplifies the structure of the spec file which is complex and nested - -Note 2: Mention how you can check to see how these 2 docs are used in the written templates e.g node.js template -Note 3: https://github.com/asyncapi/template-for-generator-templates#template-context -Note 4: Both files are passed to the renderer engines ie React ans nunjucks -Note 5: You get access to these 2 files in the templates you will use -Note 6: Adv of one over the other -Note 7: Link to the parser docs or talk about the parser -Note 8: Show the structure of the asyncapiDocument as a code snippet -Note 9: Listen to the last section of the recording again \ No newline at end of file From 3fdf810d1a0ee7d624359bdf87651dddd5058d55 Mon Sep 17 00:00:00 2001 From: Florence-Njeri Date: Thu, 14 Dec 2023 20:22:01 +0300 Subject: [PATCH 03/10] draft 1 --- docs/model-generation.md | 95 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 docs/model-generation.md diff --git a/docs/model-generation.md b/docs/model-generation.md new file mode 100644 index 000000000..79c0ac29a --- /dev/null +++ b/docs/model-generation.md @@ -0,0 +1,95 @@ +--- +title: "Generating models and classes using Modelina" +weight: 200 +--- + +Suppose you want to generate models for your application from the data types you have using the asyncapi generator. Then you should use modelina instead of the asyncapi generator with a template. + +Modelina is an AsyncAPI library that is used to generate data models using inputs such as AsyncAPI, OpenAPI or JSON schema inputs. + +This tutorial teaches you how to generate a model class using a Python MQTT client. You'll use the Modelina library and the asyncapi CLI to generate Python data models. You'll create a model schema to create and test your model code using an MQTT client. + +## Prerequisites +In this tutorial, we will use an existing [MQTT Python project](https://github.com/derberg/python-mqtt-client-template). To get an in-depth understanding of what it does, please go through the [generator template tutorial](https://www.asyncapi.com/docs/tools/generator/generator_template). +Additionally, you'll need to add the following configurations to your project: +1. Add the modelina dependency to the `package.json` file in your project + + ```json + "dependencies": { + ... + "@asyncapi/modelina": "^2.0.5" + ... + }, + ``` +2. Install modelina using the following command: + + `npm -i s @asyncapi/modelina` + + +## Background context + +### asyncapi.yml file +Explain about the relevance of channels and properties to the generated models + +## Create a model.js file +The **model.js** file is used to define the logic for your model. Inside the template folder, create a new folder src/models and add a **model.js** file to the models folder and add the code snippet below: + +```js +// 1 +import { File } from '@asyncapi/generator-react-sdk'; +// 2 +import { PythonGenerator, FormatHelpers } from '@asyncapi/modelina'; + +/** + * @typedef RenderArgument + * @type {object} + * @property {AsyncAPIDocument} asyncapi received from the generator. + */ + +/** + * Render all schema models + * @param {RenderArgument} param0 + * @returns + */ + +// 3 +export default async function schemaRender({ asyncapi }) { + // Instantiate the model generator + const pythonGenerator = new PythonGenerator(); +// 4 + const models = await pythonGenerator.generate(asyncapi); + + const files = []; + + for (const model of models) { + // 5 + const modelFileName = `${FormatHelpers.toPascalCase(model.modelName)}.py`; + // 6 + files.push({model.result}); + } +// 7 + return files; +} +``` + +The code snippet above does the following: + +1. Generate a file using the generator react sdk. +2. Import modelina (should have installed it first). +3. Define a function schemaRender** that is responsible for rendering the generated schema documents. +4. Instantiate the model generator. +5. Generates an array of Python model classes. +6. Format the generated model, comes from modelina, to Pascal case. +7. Add filenames and the model schemas(contents the contents of the model class) to the files array. +8. Return an array of files to the generator engine. + +## Model generation +Using the asyncapi cli, generate your model by running the following command: + +`asyncapi generate fromTemplate test/fixtures/asyncapi.yml ./ -o test/project --force-write --param server=dev` + +You should see the following output on your command line: +![](https://imgur.com/W2FGK1c.png) + +Navigate to test/project folder and you should see that your model template generated two modelsin the src/models folder + From 3690a804962d0849761d549b960fe556a11ff689 Mon Sep 17 00:00:00 2001 From: Florence-Njeri Date: Sat, 23 Dec 2023 13:52:00 +0300 Subject: [PATCH 04/10] add tutorial to generate models using modelina --- docs/index.md | 7 +++ docs/model-generation.md | 91 +++++++++++++++++++++++------------- docs/template-development.md | 3 ++ 3 files changed, 69 insertions(+), 32 deletions(-) diff --git a/docs/index.md b/docs/index.md index c8d2ca260..074a84723 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,6 +5,8 @@ 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. +> :memo: **Note:** To generate models/classes for your event-driven architecture apps, use [modelinna](generator/model-generation), which is supported in the AsyncAPI CLI, instead of using the AsyncAPI generator. + ### Generator use cases - Generation of interactive and understandable API documentation - Generation of APIs' client libraries @@ -51,3 +53,8 @@ graph LR D --> K[Anything else] ``` **`params`** are template-specific options passed to the `asyncapi generate fromTemplate` CLI command to customize the generated output. + +> **Remember:** +If your primary goal is to generate models from an AsyncAPI document, it is recommended to use the [Modelina library](generator/model-generation). Modelina is specifically designed for model generation and provides utilities for working with the AsyncAPI document. +However, if your requirements involve generating comprehensive documentation, code, and anything beyond models, it is advisable to use the AsyncAPI Generator. +Choose the tool that best fits your specific use case: Modelina for model generation, and the AsyncAPI Generator for more extensive code and documentation generation. diff --git a/docs/model-generation.md b/docs/model-generation.md index 79c0ac29a..e1a4ee9b6 100644 --- a/docs/model-generation.md +++ b/docs/model-generation.md @@ -3,16 +3,30 @@ title: "Generating models and classes using Modelina" weight: 200 --- -Suppose you want to generate models for your application from the data types you have using the asyncapi generator. Then you should use modelina instead of the asyncapi generator with a template. +Suppose you want to generate models for your application from the data types you have using the asyncapi generator. Then you should use Modelina instead of the asyncapi generator with a template. -Modelina is an AsyncAPI library that is used to generate data models using inputs such as AsyncAPI, OpenAPI or JSON schema inputs. +[Modelina](https://www.asyncapi.com/tools/modelina) is an AsyncAPI library that is used to generate data models using inputs such as AsyncAPI, OpenAPI or JSON schema inputs. This library helps generate data models based on your AsyncAPI document, the model template (which defines the message payloads) via the asyncapi CLI. You can then use the generated models in your code, and you can store the generated models in a single file. This tutorial will guide you through generating a model class for a Python MQTT client using Modelina and the AsyncAPI CLI. -This tutorial teaches you how to generate a model class using a Python MQTT client. You'll use the Modelina library and the asyncapi CLI to generate Python data models. You'll create a model schema to create and test your model code using an MQTT client. +In this tutorial: + +1. You'll learn how to generate a model class using a Python MQTT client. +2. You'll use the Modelina library and the asyncapi CLI to generate Python data models. +3. You'll create a model schema to test your model code using an MQTT client. ## Prerequisites -In this tutorial, we will use an existing [MQTT Python project](https://github.com/derberg/python-mqtt-client-template). To get an in-depth understanding of what it does, please go through the [generator template tutorial](https://www.asyncapi.com/docs/tools/generator/generator_template). -Additionally, you'll need to add the following configurations to your project: -1. Add the modelina dependency to the `package.json` file in your project + +This tutorial builds upon an existing project, the [MQTT Python project](https://github.com/derberg/python-mqtt-client-template). The project creates a custom generator template using a Python MQTT client. We'll use the same project to create a simple Modelina template and generate data models using the Python MQTT client. To get an in-depth understanding of what this project does, please go through the [generator template tutorial](https://www.asyncapi.com/docs/tools/generator/generator_template). + +You should also have [Node.js and npm](https://nodejs.org/en/download/) and the [AsyncAPI CLI](https://www.asyncapi.com/docs/tools/generator/installation-guide#asyncapi-cli) installed in your machine. + +> :memo: **Note:** When building the model from scratch, you'll need to have a predefined [AsyncAPI document](https://www.asyncapi.com/docs/tools/generator/asyncapi-document) and you can also use the existing [community-maintained templates](https://www.asyncapi.com/docs/tools/generator/template#generator-templates-list) instead of creating a template from scratch. + +## Getting started + +First, clone the MQTT Python project from Github using the following command: +`git clone https://github.com/derberg/python-mqtt-client-template` +Open the Python MQTT project in your code editor +Then, add the Modelina dependency to the `package.json` file in your project: ```json "dependencies": { @@ -21,18 +35,19 @@ Additionally, you'll need to add the following configurations to your project: ... }, ``` -2. Install modelina using the following command: - `npm -i s @asyncapi/modelina` +Finally, install Modelina in your project using npm: + `npm install @asyncapi/modelina` -## Background context +## Generating models -### asyncapi.yml file -Explain about the relevance of channels and properties to the generated models +With Modelina installed, you can now generate models using an AsyncAPI document as an input. In the next section, you'll create a `model.js` file to define the logic of your model(s). -## Create a model.js file -The **model.js** file is used to define the logic for your model. Inside the template folder, create a new folder src/models and add a **model.js** file to the models folder and add the code snippet below: +### Create a model.js file + +Create a new folder in the **template** directory named **src/models** and create a **models.js** file within it. +Then in the model.js file, add the following code: ```js // 1 @@ -54,42 +69,54 @@ import { PythonGenerator, FormatHelpers } from '@asyncapi/modelina'; // 3 export default async function schemaRender({ asyncapi }) { - // Instantiate the model generator + // 4 const pythonGenerator = new PythonGenerator(); -// 4 +// 5 const models = await pythonGenerator.generate(asyncapi); - +// 6 const files = []; for (const model of models) { - // 5 + // 7 const modelFileName = `${FormatHelpers.toPascalCase(model.modelName)}.py`; - // 6 + // 8 files.push({model.result}); } -// 7 +// 9 return files; } ``` -The code snippet above does the following: +Let's break it down. The code snippet above does the following: + +1. Imports the **File** component from the [generator react SDK](https://github.com/asyncapi/generator-react-sdk). This tells the generator CLI to use the [react render engine](https://www.asyncapi.com/docs/tools/generator/react-render-engine) to generate a model file or files as output. +2. Import Modelina into your template. The Modelina library makes the **PythonGenerator** and the **FormatHelpers** used to format the generated Python code available to your model template. +3. Define an asynchronous function **schemaRender** that get's invoked everytime the generator CLI runs the **models.js** template. This function is responsible for rendering the generated schema files. It also takes the `asyncapi` object as an input parameter. +4. Instantiates the **PythonGenerator** model generator from Modelina. It will be used to generate Python code from the AsyncAPI document. +5. Generates an array of Python model classes from the `asyncapi` (AsyncAPI document) object received from the generator. +6. Define an empty array **files** to store the generated model files. +7. Iterates over each generated model and formats the generated model names to Pascal case. +8. Add filenames and the model schemas to the **files** array. +9. Return an array of files, each representing the generated model classes, to the generator engine. -1. Generate a file using the generator react sdk. -2. Import modelina (should have installed it first). -3. Define a function schemaRender** that is responsible for rendering the generated schema documents. -4. Instantiate the model generator. -5. Generates an array of Python model classes. -6. Format the generated model, comes from modelina, to Pascal case. -7. Add filenames and the model schemas(contents the contents of the model class) to the files array. -8. Return an array of files to the generator engine. +## Model generation using the AsyncAPI CLI -## Model generation -Using the asyncapi cli, generate your model by running the following command: +Using the AsyncAPI CLI, generate your model by running the following command: `asyncapi generate fromTemplate test/fixtures/asyncapi.yml ./ -o test/project --force-write --param server=dev` -You should see the following output on your command line: +If successful, you should see the following output on your terminal: ![](https://imgur.com/W2FGK1c.png) -Navigate to test/project folder and you should see that your model template generated two modelsin the src/models folder +Since you defined your model in **src/models** the generated model schema will be in the **test/project -> src/models** directory. +Navigate to **test/project** folder and you should see that your model template generated two models in the **src/models** folder. +Let's break down the previous command: + +`asyncapi generate fromTemplate` is how you use AsyncAPI generator via the AsyncAPI CLI. +`test/fixtures/asyncapi.yml`` points to your AsyncAPI document. +`./` specifies the location of your model template. +`-o` specifies where to output the generated data models. + +## Conclusion +Modelina provides a flexible and powerful way to generate data models from AsyncAPI, OpenAPI, or JSON Schema documents. With the AsyncAPI CLI, you can easily generate models and integrate them into your development workflow. With the ability to customize the generated models, Modelina proves to be a valuable tool in the development of event-driven architectures. diff --git a/docs/template-development.md b/docs/template-development.md index 35af42ce4..55e0409a7 100644 --- a/docs/template-development.md +++ b/docs/template-development.md @@ -2,6 +2,9 @@ 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 [Modelina](generator/model-generation) a dedicated library for model generation. + ## Minimum template requirements From bd6d6eef2ec022fe02bcb5a976f44a51c4f8be0c Mon Sep 17 00:00:00 2001 From: Florence-Njeri Date: Sat, 23 Dec 2023 14:13:30 +0300 Subject: [PATCH 05/10] editorial --- docs/index.md | 8 ++------ docs/model-generation.md | 18 ++++++++++++------ docs/template-development.md | 1 - 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/index.md b/docs/index.md index 074a84723..8927df67c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,7 +5,8 @@ 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. -> :memo: **Note:** To generate models/classes for your event-driven architecture apps, use [modelinna](generator/model-generation), which is supported in the AsyncAPI CLI, instead of using the AsyncAPI generator. +> :memo: **Note:** +> If your primary objective is to generate models/classes for your event-driven architecture apps, use [modelina](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 @@ -53,8 +54,3 @@ graph LR D --> K[Anything else] ``` **`params`** are template-specific options passed to the `asyncapi generate fromTemplate` CLI command to customize the generated output. - -> **Remember:** -If your primary goal is to generate models from an AsyncAPI document, it is recommended to use the [Modelina library](generator/model-generation). Modelina is specifically designed for model generation and provides utilities for working with the AsyncAPI document. -However, if your requirements involve generating comprehensive documentation, code, and anything beyond models, it is advisable to use the AsyncAPI Generator. -Choose the tool that best fits your specific use case: Modelina for model generation, and the AsyncAPI Generator for more extensive code and documentation generation. diff --git a/docs/model-generation.md b/docs/model-generation.md index e1a4ee9b6..b40b398cb 100644 --- a/docs/model-generation.md +++ b/docs/model-generation.md @@ -19,13 +19,16 @@ This tutorial builds upon an existing project, the [MQTT Python project](https:/ You should also have [Node.js and npm](https://nodejs.org/en/download/) and the [AsyncAPI CLI](https://www.asyncapi.com/docs/tools/generator/installation-guide#asyncapi-cli) installed in your machine. -> :memo: **Note:** When building the model from scratch, you'll need to have a predefined [AsyncAPI document](https://www.asyncapi.com/docs/tools/generator/asyncapi-document) and you can also use the existing [community-maintained templates](https://www.asyncapi.com/docs/tools/generator/template#generator-templates-list) instead of creating a template from scratch. +> :memo: **Note:** +> When building the model from scratch, you'll need to have a predefined [AsyncAPI document](https://www.asyncapi.com/docs/tools/generator/asyncapi-document) and you can also use the existing [community-maintained templates](https://www.asyncapi.com/docs/tools/generator/template#generator-templates-list) instead of creating a template from scratch. ## Getting started First, clone the MQTT Python project from Github using the following command: `git clone https://github.com/derberg/python-mqtt-client-template` + Open the Python MQTT project in your code editor + Then, add the Modelina dependency to the `package.json` file in your project: ```json @@ -106,16 +109,19 @@ Using the AsyncAPI CLI, generate your model by running the following command: `asyncapi generate fromTemplate test/fixtures/asyncapi.yml ./ -o test/project --force-write --param server=dev` If successful, you should see the following output on your terminal: -![](https://imgur.com/W2FGK1c.png) +``` +Generation in progress. Keep calm and wait a bit... done +Check out your shiny new generated files at test/project. +``` Since you defined your model in **src/models** the generated model schema will be in the **test/project -> src/models** directory. Navigate to **test/project** folder and you should see that your model template generated two models in the **src/models** folder. Let's break down the previous command: -`asyncapi generate fromTemplate` is how you use AsyncAPI generator via the AsyncAPI CLI. -`test/fixtures/asyncapi.yml`` points to your AsyncAPI document. -`./` specifies the location of your model template. -`-o` specifies where to output the generated data models. +- `asyncapi generate fromTemplate` is how you use AsyncAPI generator via the AsyncAPI CLI. +- `test/fixtures/asyncapi.yml` points to your AsyncAPI document. +- `./` specifies the location of your model template. +- `-o` specifies where to output the generated data models. ## Conclusion diff --git a/docs/template-development.md b/docs/template-development.md index 55e0409a7..3dfbc150e 100644 --- a/docs/template-development.md +++ b/docs/template-development.md @@ -5,7 +5,6 @@ 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 [Modelina](generator/model-generation) a dedicated library for model generation. - ## Minimum template requirements Let's break down the minimum template requirements: the `template` directory and a `package.json` file. From ce963b7dd1b66dd5f1b91e853d5b58f579ec4bd2 Mon Sep 17 00:00:00 2001 From: Florence Njeri <40742916+Florence-Njeri@users.noreply.github.com> Date: Thu, 4 Jan 2024 19:35:50 +0300 Subject: [PATCH 06/10] Apply suggestions from code review editorial from Lukasz Co-authored-by: Lukasz Gornicki --- docs/index.md | 4 ++-- docs/model-generation.md | 4 +++- docs/template-development.md | 2 +- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/index.md b/docs/index.md index 8927df67c..0c32dbd82 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,8 +5,8 @@ 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. -> :memo: **Note:** -> If your primary objective is to generate models/classes for your event-driven architecture apps, use [modelina](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. +> **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 diff --git a/docs/model-generation.md b/docs/model-generation.md index b40b398cb..e7d21417d 100644 --- a/docs/model-generation.md +++ b/docs/model-generation.md @@ -3,7 +3,9 @@ title: "Generating models and classes using Modelina" weight: 200 --- -Suppose you want to generate models for your application from the data types you have using the asyncapi generator. Then you should use Modelina instead of the asyncapi generator with a template. +Use [AsyncAPI Modelina](/tools/modelina) to generate models for an application. Since models generation is something that you usually perform as an automated step through CI/CD, best way to use Modelina is through [AsyncAPI CLI](/tools/cli). + +In case you work on a template for generating an application and part of template responsibilities is to provide models, you should integrate Modelina library instead of templating model structures using features from AsyncAPI Generator. [Modelina](https://www.asyncapi.com/tools/modelina) is an AsyncAPI library that is used to generate data models using inputs such as AsyncAPI, OpenAPI or JSON schema inputs. This library helps generate data models based on your AsyncAPI document, the model template (which defines the message payloads) via the asyncapi CLI. You can then use the generated models in your code, and you can store the generated models in a single file. This tutorial will guide you through generating a model class for a Python MQTT client using Modelina and the AsyncAPI CLI. diff --git a/docs/template-development.md b/docs/template-development.md index 3dfbc150e..c0a29c060 100644 --- a/docs/template-development.md +++ b/docs/template-development.md @@ -3,7 +3,7 @@ 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 [Modelina](generator/model-generation) a dedicated library for model generation. +> 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 From 46e67221c48de027a5b762ecf93ed3ab6170338a Mon Sep 17 00:00:00 2001 From: Florence-Njeri Date: Tue, 9 Jan 2024 17:44:44 +0300 Subject: [PATCH 07/10] PR feedback from Lukasz --- docs/installation-guide.md | 2 +- docs/model-generation.md | 58 +++++++++++++++--------------------- docs/template-development.md | 2 +- docs/template.md | 2 +- docs/usage.md | 6 ++-- 5 files changed, 30 insertions(+), 40 deletions(-) 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 index b40b398cb..0b7ea038c 100644 --- a/docs/model-generation.md +++ b/docs/model-generation.md @@ -1,35 +1,32 @@ --- -title: "Generating models and classes using Modelina" +title: "How to generating models and classes using Modelina" weight: 200 --- -Suppose you want to generate models for your application from the data types you have using the asyncapi generator. Then you should use Modelina instead of the asyncapi generator with a template. +This guide will walk you through the process of generating models and classes using [Modelina](https://www.asyncapi.com/tools/modelina) and the asyncapi generator. If you want to generate models for your application from the data types, you should use Modelina instead of the asyncapi generator with a template else you should use [Modelina](https://www.asyncapi.com/tools/modelina) is an AsyncAPI library that is used to generate data models using inputs such as AsyncAPI, OpenAPI or JSON schema inputs. This library helps generate data models based on your AsyncAPI document, the model template (which defines the message payloads) via the asyncapi CLI. You can then use the generated models in your code, and you can store the generated models in a single file. This tutorial will guide you through generating a model class for a Python MQTT client using Modelina and the AsyncAPI CLI. -In this tutorial: +In this guide, you'll learn to: -1. You'll learn how to generate a model class using a Python MQTT client. -2. You'll use the Modelina library and the asyncapi CLI to generate Python data models. -3. You'll create a model schema to test your model code using an MQTT client. +1. Generate a model class using a Python MQTT client. +2. Use the Modelina library and the asyncapi CLI to generate Python data models. +3. Create a model schema to test your model code using an MQTT client. ## Prerequisites - -This tutorial builds upon an existing project, the [MQTT Python project](https://github.com/derberg/python-mqtt-client-template). The project creates a custom generator template using a Python MQTT client. We'll use the same project to create a simple Modelina template and generate data models using the Python MQTT client. To get an in-depth understanding of what this project does, please go through the [generator template tutorial](https://www.asyncapi.com/docs/tools/generator/generator_template). - -You should also have [Node.js and npm](https://nodejs.org/en/download/) and the [AsyncAPI CLI](https://www.asyncapi.com/docs/tools/generator/installation-guide#asyncapi-cli) installed in your machine. +Before you begin, ensure you have the following installed: +- [Node.js and npm](https://nodejs.org/en/download/). +- [AsyncAPI CLI](https://www.asyncapi.com/docs/tools/generator/installation-guide#asyncapi-cli) installed in your machine. > :memo: **Note:** > When building the model from scratch, you'll need to have a predefined [AsyncAPI document](https://www.asyncapi.com/docs/tools/generator/asyncapi-document) and you can also use the existing [community-maintained templates](https://www.asyncapi.com/docs/tools/generator/template#generator-templates-list) instead of creating a template from scratch. ## Getting started -First, clone the MQTT Python project from Github using the following command: -`git clone https://github.com/derberg/python-mqtt-client-template` - -Open the Python MQTT project in your code editor +First, install Modelina in your project using npm: -Then, add the Modelina dependency to the `package.json` file in your project: + `npm install --save @asyncapi/modelina` +This command will then automatically add the modelina dependency to your `package.json` as shown below: ```json "dependencies": { @@ -39,10 +36,6 @@ Then, add the Modelina dependency to the `package.json` file in your project: }, ``` -Finally, install Modelina in your project using npm: - - `npm install @asyncapi/modelina` - ## Generating models With Modelina installed, you can now generate models using an AsyncAPI document as an input. In the next section, you'll create a `model.js` file to define the logic of your model(s). @@ -92,9 +85,9 @@ export default async function schemaRender({ asyncapi }) { Let's break it down. The code snippet above does the following: -1. Imports the **File** component from the [generator react SDK](https://github.com/asyncapi/generator-react-sdk). This tells the generator CLI to use the [react render engine](https://www.asyncapi.com/docs/tools/generator/react-render-engine) to generate a model file or files as output. +1. Imports the **File** component from the [generator react SDK](https://github.com/asyncapi/generator-react-sdk). This tells the AsyncAPI CLI to use the [react render engine](https://www.asyncapi.com/docs/tools/generator/react-render-engine) to generate a model file or files as output. 2. Import Modelina into your template. The Modelina library makes the **PythonGenerator** and the **FormatHelpers** used to format the generated Python code available to your model template. -3. Define an asynchronous function **schemaRender** that get's invoked everytime the generator CLI runs the **models.js** template. This function is responsible for rendering the generated schema files. It also takes the `asyncapi` object as an input parameter. +3. Define an asynchronous function **schemaRender** that get's invoked everytime the AsyncAPI CLI runs the **models.js** template. This function is responsible for rendering the generated schema files. It also takes the `asyncapi` object as an input parameter. 4. Instantiates the **PythonGenerator** model generator from Modelina. It will be used to generate Python code from the AsyncAPI document. 5. Generates an array of Python model classes from the `asyncapi` (AsyncAPI document) object received from the generator. 6. Define an empty array **files** to store the generated model files. @@ -102,27 +95,24 @@ Let's break it down. The code snippet above does the following: 8. Add filenames and the model schemas to the **files** array. 9. Return an array of files, each representing the generated model classes, to the generator engine. -## Model generation using the AsyncAPI CLI +## Generate models +Use the AsyncAPI CLI to generate your models using the following command: -Using the AsyncAPI CLI, generate your model by running the following command: - -`asyncapi generate fromTemplate test/fixtures/asyncapi.yml ./ -o test/project --force-write --param server=dev` +``` +asyncapi generate fromTemplate test/fixtures/asyncapi.yml ./ -o test/project --force-write --param server=dev +``` +If successful, you should see the following output: -If successful, you should see the following output on your terminal: ``` Generation in progress. Keep calm and wait a bit... done Check out your shiny new generated files at test/project. ``` -Since you defined your model in **src/models** the generated model schema will be in the **test/project -> src/models** directory. -Navigate to **test/project** folder and you should see that your model template generated two models in the **src/models** folder. -Let's break down the previous command: - -- `asyncapi generate fromTemplate` is how you use AsyncAPI generator via the AsyncAPI CLI. -- `test/fixtures/asyncapi.yml` points to your AsyncAPI document. -- `./` specifies the location of your model template. -- `-o` specifies where to output the generated data models. +Navigate to test/project/src/models to find your generated model files. ## Conclusion Modelina provides a flexible and powerful way to generate data models from AsyncAPI, OpenAPI, or JSON Schema documents. With the AsyncAPI CLI, you can easily generate models and integrate them into your development workflow. With the ability to customize the generated models, Modelina proves to be a valuable tool in the development of event-driven architectures. + +>Note: +>You can integrate this example into your own template by following the [generator template tutorial](https://www.asyncapi.com/docs/tools/generator/generator-template). Ensure that you add `@asyncapi/modelina` to template dependencies using `npm install --save @asyncapi/modelina``. diff --git a/docs/template-development.md b/docs/template-development.md index 3dfbc150e..5a47b277c 100644 --- a/docs/template-development.md +++ b/docs/template-development.md @@ -132,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 e47ebecc8..c79d846df 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..78a715fe7 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