From bd6d6eef2ec022fe02bcb5a976f44a51c4f8be0c Mon Sep 17 00:00:00 2001 From: Florence-Njeri Date: Sat, 23 Dec 2023 14:13:30 +0300 Subject: [PATCH] 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.