Add new AsyncAPI tool to website

Introduction

Learn how to add your tool to the AsyncAPI website using the .asyncapi-tool file. Make sure to structure your .asyncapi-tool file correctly to render your tool on the AsyncAPI website with customized tags and information for users to filter tools according to different categories.

The entire AsyncAPI Tools list is under the AsyncAPI Tools Dashboard page.

AsyncAPI tool file

The .asyncapi-tool file requires a specific schema to describe the type and details of your AsyncAPI tool; this file automatically adds your tool to our website's Tools Dashboard within a week. Every Monday, we run our workflow to add new tools or update existing tools in our website and thus, notifies us regarding the wrong format of the file used somewhere in Github using Slack notifications. You can even ask the maintainers to manually trigger workflow by Creating a Github issue or contact us via AsyncAPI Slack.

You must create and maintain your .asyncapi-tool file in your tool's repository, as it doesn't require AsyncAPI approval. There is no restriction on the directory in which the file has to be created. In case, you need to create 2 or more .asyncapi-tool files in same repository, you can do the same, just make sure you provide correct repoUrl for each of them. Same case applies for monorepo as well.

Tool file structure

Let's look at a sample .asyncapi-tool file in JSON and YAML structures. You'll use these file structures to insert your tool into the website's Tools Dashboard.

JSON format file structure

1{
2  "title": "Sample Tool",
3  "description": "Tool for testing purposes in AsyncAPI",
4  "links": {
5    "websiteUrl": "https://akshatnema.netlify.app",
6    "docsUrl": "https://akshatnema.vercel.app",
7    "repoUrl": "https://github.com/akshatnema/Login-Registration-project/"
8  },
9  "filters": {
10    "language": "javascript",
11    "technology": ["react"],
12    "categories": ["code-generator"],
13    "hasCommercial": true
14  }
15}

YAML format file structure

1---
2title: Sample Tool
3description: Tool for testing
4links:
5  websiteUrl: https://akshatnema.netlify.app
6  docsUrl: https://akshatnema.vercel.app
7  repoUrl: https://github.com/akshatnema/Login-Registration-project/
8filters:
9  language: javascript
10  technology:
11  - react
12  categories:
13  - code-generator
14  hasCommercial: true

Let's break down each field of an .asyncapi-tool file:

You can also follow a simple example of .asyncapi-tool file to render the tool in website. This is example of AsyncAPI Bundler. .asyncapi-tool file in YAML format:

1title: AsyncAPI Bundler
2filters:
3    languages:
4        - TypeScript
5    technology:
6        - TypeScript
7    categories:
8        - bundler

Manual addition of tools

If you don't want to create the .asyncapi-tool file in your repository or your tool's codebase doesn't exist in Github, the AsyncAPI website repository contains a tools-manual.json file that adds your tool to our website's Tools Dashboard.

Inside this tools-manual.json file, you must choose the desired category for your tool and add your tool as an element inside that particular category object.

JSON tool structure

Once you've created your .asyncapi-tool file, check your tool configuration inside our database on the tools-automated.json file.

Here's what a sample JSON object for an AsyncAPI tool should look like after it is added to the final tools.json that keeps the information about all tools added manually and through .asyncapi-tool file:

1{
2  "title": "Sample Tool",
3  "description": "Tool for testing",
4  "links": {
5    "websiteUrl": "https://akshatnema.netlify.app",
6    "docsUrl": "",
7    "repoUrl": "https://github.com/akshatnema/Login-Registration-project"
8  },
9  "filters": {
10    "language": "javascript",
11    "technology": ["react"],
12    "categories": ["code-generator"],
13    "hasCommercial": false,
14    "isAsyncAPIOwner": false
15  }
16}

If your tool's information isn't showing up correctly in this file, please create a new AsyncAPI GitHub issue or contact us via AsyncAPI Slack.

Adding New Category

The category list is available in the categorylist.ts file from where you can opt the best category for your tools. Moreoever, if you don't find any, you can send us a request to add a new category that goes best with your requirements.

You can also create a Pull Request by adding a new category object in the categorylist.ts file providing all the details/information about the new category, as follows:

1{
2  name: "Sample category name",
3  tag: "sample-tag",
4  description: "Description providing some information about the category and other nitty-gritty things about the category."
5}

Also, add the new category details in the tools-manual.json file with proper json schema, as well.

1  "Sample category name": {
2    "description": "Description that provides some information about the category and other nitty-gritty things about the category.",
3    "toolsList": []
4  }