AsyncAPI AsyncAPI Conf 2022, 3 Nov 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: A Beginner's Guide to Generator Tool Use-cases - Pratik Arvind Haldankar, AsyncAPI Initiative

Description

AsyncAPI Conference 2022 - Day 1
3rd November 2022

Generator is a tool that you can use to generate whatever you want based on the AsyncAPI specification file as an input. By using this tool, I can easily automate the code and docs generation process. I can just modify the readily available list of Templates by AsyncAPI organization, provide an input file and automatically generate whatever I need. In this talk, The speaker will cover a few introductory use cases of the Generator library & give a brief demo on how to generate code/docs using the Generator tool. By the end of this talk, the audience will get introduced to - Why the generator tool should be used & how it can help you in your work (Use cases) and How they can actually use it (Beginner level demo of how they can generate code/docs).

A

Hello, everyone I hope you're doing fine, welcome to async API conference 2022. Thank you. So much for joining my name is pratik. I am a student, a technical writer and a computer engineer currently studying in India.

A

I am a open source contributor and a technical writing intern and async API initiatives.

A

During the past few months, I had the opportunity on working on generator 2 documentation as the part of Google season of dogs program 2022, while working on the documentation I got to use generator and play around with some of its soldiers.

A

Today's conference I will be walking you through a beginner's guide on some of the generator tool use cases after that, I will be also giving you a demo on how to generate documentation with async API generator itself.

A

Before we move forward, here are the things that we are going to cover in today's talk, what is generator in this section? I will be covering what generator is and what it can be used for.

A

When we talk about generator, there are two components which are very essential to the generator Library.

A

In this following section, we will be discussing what these two components are and what is their purpose in the generator Library after that, we will be discussing. Why need generator in our application or projects after that, I will be listing down some of the use cases of the generator tool and finally, I will be giving a demo on how to use generator first hand to generate documentation for our application.

A

What is generator generator is a tool that we can use to generate whatever we want, based on the async API file as an input, we can use it to generate things such as code, documentation, diagrams microservices and various other applications.

A

As long as you can Define it in your async API file, there is no limit to what generator can generate to specify what exactly must be generated. We need to create a template.

A

A template is just a set of files where you describe what should be the result of the generation process depending on the contents of the async API file we had provided. So we just encountered two new terms here. The first is async API file and the second is template.

A

What is async API file? First, a Sync API specification file is a yaml or Json file, which we provide to the generator as an input. This file can be both in the form of the amble or Json, but in most cases it is in yaml form only generator, then fetches. The contents of this Asic API file using a library called as arborist then generator produces the output primarily based on the contents of that async API specification file.

A

The following image shows how a sample async, API specification file, looks like this asyncopy. This async API specification file is a dummy file. We can use in your projects. You can find it on async api's, GitHub repositories in the following demo. We are going to use this same file to generate documentation.

A

Template is a project that specifies what exactly you get as an output, music generator and the async API file as an input, as opposed to as opposed to an async API file. Generator knows what presented, because you supplement it with a generator template. You see. Async API has a list of rarely available templates that you can use in your application.

A

Some of these templates include marked out template, HTML template PHP templates, python templates and much more. You can find all of them in async, apis official GitHub profile.

A

Why should we use generator Mission, while working on the generator I realized that generator it's very quick to set up and easier to use on a regular basis? Generator is perfect for a fertilization of complex documents.

A

As we discussed earlier, there are number of community maintenance cabinet templates that you can use directly in your projects.

A

Generator helps in generation of interactive and understandable API documentation generator has a built-in command line. Interface support.

A

There are some use, cases of generator generator, obviously can be used for basic code generation.

A

It can be used to generate documentation in the form of both HTML, as well as markdown generator supports both of these formats on document generation generator can be used to produce microservice applications.

A

There are multiple templates available which help generator in producing Java or python application. Along with that, there are many use case you can find in the generator tool.

A

Before you actually install the generator tool, there are some requirements. We need to meet.

A

Generator in its engine node.js application. Therefore, you need to have a node.node.js version, 12.16 or higher in order to use the latest features of generator.

A

We need to have an npn version 6.30 or higher after the requirements are satisfied. You can install the generator Library globally to use its CNF.

A

The following npm command will install the generator Library globally on your local machine. If you already have the generator installed on your local machine executing this command will update the generator on your local machine to its latest version.

A

Demo. Here I will be giving you demo on how to generate markdown documentation using async, API generator and a template.

A

So, as we had discussed, we are going to generate documentation for both HTML as well as markdown, with the help of generator templates and async API specification form the in the screen. You can see the sample facing API specification file that we had discussed about in the previous lines.

A

We are going to input this AC kpi specification file to the generator.

A

Also have an HTML template. This template is developed and managed by Asic API, and you can use this directly to your projects.

A

You can just copy or download this folder on your local machine.

A

Here I have loaded this HTML template in my various code on my iPhone machine.

A

So the first thing we have to do is download the generator Library.

A

If you do not have generator Library installed, it will obviously install the library globally on your machine and if you have the generator Library already installed, it will update the existing version to the latest.

A

Here it is downloading some libraries.

A

See the generator library is installed in our system, so in the next step, I am going to produce the output documentation. So the first argument is kg which stands for async Epi generator. The second argument is supposed to be the asynpy file that we are going to feed as an input position Twitter, so I am just going to copy down this link.

A

The next argument is the template that that you are going to be using.

A

So here I am using HTML template.

A

And the next argument is the output flag, along with the folder in which you want your output to be.

A

For the generation process has become.

A

As we can see the output generated in the formula, html.com templates, let's take a look at it.

A

As you can see, the documentation for the HTML template has been updated. The output is only based on the contents in the AC KPS specification file.

A

Everything along with title, spoke cut. Tens and four blocks are all fetched from async API specification file and displayed as an output. We will be doing the same for markdown Tech grid as well. Just like the HTML template basic API specification file for the templates. We we will be using a tip markdog, definite provided by Asic API, just copy those port for download the zip again.

A

So here also I have loaded uh the markdown different on my local vs4.

A

This step is same.

A

First, we give the GB stands for 360 image of data. Second, we give the Asic API ml file as an input to this theater. The third argument is the AC kpi template of choice. Here, it's markdown template.

A

And the final argument is the output flag, along with the folder.

A

So, as we can see, the markdown file is operated with the same contents, but this time instead of HTML this file, this file is in the form of markbon file, everything down from title to a table and follows it. Contents are exactly same as HTML, but the format is different. The content again is fetched from the dummy async API file.

A

As you can see here, this template has a section for a hopes which we talked about. This section contains pieces of fold which help us enhance Our Generation process.

A

Here we have been given some supported parameters that we can use with our basic API generator Library.

A

So as sidebar organization based version single file list, PDF, config Etc, this supported parameters helps our generator achieve many things, but, for example, setting this previous flag will also Download a pdf version of whatever our output was, for example, the documentation which Associated, along with the HTML version or the markdown version. A pdf version will also be generated on our local system in the same folder.

A

And in inside the redmi of every template, there are development, hence given.

A

Along with every template, there are details given in the redmi file, such as use a supported parameters, development, heads and contributors a little markdown.

A

Here we have various supported parameters such as front matter file, name, POC version, let's out file it, for example, uh gives the file name of the output file POC, for example. If we set it to draw, it will include a table of contents in the output model.

A

Here also we have various sections, such as you've. Just supported parameters, development and containers generator cln, then so a basic command to generate output has three main components. First, is the AG stands for async page in the second component? Is the async API specification file, which will we are providing as an input to the generator? The third is the HTML template we are using here. You can use any template, you want and the final uh and the final component is the output flag and the folder name in which output will be saved.

A

uh Thank you so much for joining me in this talk. You can follow me on Twitter at pratik haldankar. You can format LinkedIn as well add the same address. Thank you so much for having me.