AsyncAPI is an open-source specification for describing asynchronous APIs. Creating a template for AsyncAPI involves defining the structure and content of your asynchronous API.
Understand the AsyncAPI Specification
Before creating a template for Generator tool, we need to know the specification required for AsyncAPI. Read the official documentation for understanding the key components, Such as
To understand the basics refer the Official documentation of AsyncAPI.
But for a simple overview one can also refer My blog.
Choose a Template Format
AsyncAPI supports Two templating formats:
YAML (YAML Aint’s Markup Language)
JSON (JavaScript Object Notation)
For this time, We shall use YAML extension.
Define the Template Structure
Before we create our YAML ( we can also say YML) we need to follow the following file/ directory structure,
my-template
├─ asyncapi.yml
├─ package.json
└─ src
├─ components
│ └─ PdfTemplate.js
├─ App.js
└─ index.js
Once this file structure is duplicated, We can follow up with creating the package.json file first.
Package.json
In the package.json file, specify the template engine, render and other configuration options we need.
For this template we are using react rendering engine.
{
"name": "asyncapi-pdf-template",
"version": "1.0.0",
"description": "A PDF template generator for AsyncAPI specifications",
"main": "index.js",
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
},
"dependencies": {
"react": "^17.0.2",
"react-dom": "^17.0.2",
"react-scripts": "4.0.3",
"asyncapi-react": "^1.0.0",
"pdf-lib": "^1.17.1"
},
"devDependencies": {
"eslint": "^7.32.0",
"eslint-plugin-react": "^7.27.1"
},
"keywords": [],
"author": "",
"license": "ISC"
}
Creating an AsyncAPI document :
In the asyncapi.yml file, we define our event-driven API using the AsyncAPI specification. This file will serve as the input for the template generation process.
asyncapi: '2.0.0'
info:
title: My AsyncAPI PDF Template
version: '1.0.0'
description: A template for generating PDFs from AsyncAPI specifications.
servers:
production:
url: 'api.example.com'
protocol: 'wss'
channels:
myChannel:
description: A channel for sending messages.
subscribe:
operationId: receiveMessage
summary: Receive a message
message:
contentType: application/json
payload:
type: object
properties:
message:
type: string
Creating PDF template component:
In the src/components/PdfTemplate.js file, create a react component that will render the PDF template. This component has to import the FILE component from @asyncapi/generator-react-sdk and use it to define the PDF file structure.
import React, { useState, useEffect } from 'react';
import { PDFDocument, rgb } from 'pdf-lib';
import PdfContent from './PdfContent';
import ReactDOMServer from 'react-dom/server';
const PdfTemplate = () => {
const [pdfBytes, setPdfBytes] = useState(null);
const [asyncapiData, setAsyncapiData] = useState({
title: 'My AsyncAPI PDF Template',
description: 'A template for generating PDFs from AsyncAPI specifications.',
channels: [
{ name: 'myChannel', description: 'A channel for sending messages.' },
],
});
const generatePdf = async () => {
const pdfDoc = await PDFDocument.create();
const page = pdfDoc.addPage([600, 400]);
// Render the PDF content using the PdfContent component
const content = (
<PdfContent
title={asyncapiData.title}
description={asyncapiData.description}
channels={asyncapiData.channels}
/>
);
// Convert the React component to a string
const contentString = ReactDOMServer.renderToStaticMarkup(content);
page.drawText(contentString, {
x: 50,
y: 350,
size: 12,
color: rgb(0, 0, 0),
});
const pdfBytes = await pdfDoc.save();
setPdfBytes(pdfBytes);
};
return (
<div>
<button onClick={generatePdf}>Generate PDF</button>
{pdfBytes && (
<a href={`data:application/pdf;base64,${pdfBytes}`} download="asyncapi.pdf">
Download PDF
</a>
)}
</div>
);
};
export default PdfTemplate;
Create the main application component:
In the src/App.js file, create a React component that will render the main application. This component should import the ‘PdfTemplate’ components and use it to generate the PDF template
import React from 'react';
import PdfTemplate from './components/PdfTemplate';
function App() {
return (
<div className="App">
<h1>AsyncAPI PDF Template</h1>
<PdfTemplate />
</div>
);
}
export default App;
Create the index component:
In the src/index.js file, create a React component that will serve as the entry point for the template generation process. This componetns should import the ‘App’ component and use it to render the main application.
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import './index.css';
ReactDOM.render(
<React.StrictMode>
<App />
</React.StrictMode>,
document.getElementById('root')
);
Installation of dependencies
After creating all the necessary javascript files and document , for running the Generator tool, we need to install the necessary dependencies in the my-template directory. we can do that by following commands.
npm install
npm install -g @asyncapi/cli
For running the Generator tool you can run the following command
#this command is the example
#asyncapi generate fromTemplate [path of your yml document] @asyncapi/[your template name] -o [path to store output]
For The file structure mentioned above the following commands suitable.
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/pdf-template
Development guide
If you want to use my code for generator tool, the following steps will guide you easily with running the code base on your local machine.
- Fork and Clone the repository
First fork the repository from github and then clone it.
<https://github.com/{your_username}/Generator-Templates>
cd Generator-Templates
For using the python-mqtt-client-template
cd python-mqtt-client-template/
npm install
cd test/project/
python3 -m venv myenv
source myenv/bin/activate
pip install package_names
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/python-paho-template
For running any other template from Generator-Templates .
Move to the directory of the template and run the following commands
npm install
npm install -g @asyncapi/cli
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/pdf-template