feat: support yaml as format for .asyncapi-tools
#1135
Conversation
derberg
requested review from
fmvilas,
mcturco,
akshatnema,
magicmatatjahu and
asyncapi-bot-eve
as code owners
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site settings. |
| {"Code-first tools":{"description":"The following is a list of tools that generate AsyncAPI documents from your code.","toolsList":[]},"Code Generators":{"description":"The following is a list of tools that generate code from an AsyncAPI document; not the other way around.","toolsList":[{"title":"Sample Tool","description":"Tool for testing","links":{"websiteUrl":"https://akshatnema.netlify.app","docsUrl":"","repoUrl":"https://github.com/akshatnema/Login-Registration-project"},"filters":{"language":"javascript","technology":["react"],"categories":["code generator"],"hasCommercial":false,"isAsyncAPIOwner":false}}]},"Converters":{"description":"The following is a list of tools that do not yet belong to any specific category but are also useful for the community.","toolsList":[]},"Directories":{"description":"The following is a list of directories that index public AsyncAPI documents.","toolsList":[]},"Documentation Generators":{"description":"The following is a list of tools that generate human-readable documentation from an AsyncAPI document.","toolsList":[]},"UI components":{"description":"The following is a list of UI components to view AsyncAPI documents.","toolsList":[]},"DSL":{"description":"Writing YAML by hand is no fun, and maybe you don't want a GUI, so use a Domain Specific Language to write AsyncAPI in your language of choice.","toolsList":[]},"Frameworks":{"description":"The following is a list of API/application frameworks that make use of AsyncAPI.","toolsList":[]},"GitHub Actions":{"description":"The following is a list of GitHub Actions that you can use in your workflows","toolsList":[]},"Mocking and Testing":{"description":"The tools below take specification documents as input, then publish fake messages to broker destinations for simulation purposes. They may also check that publisher messages are compliant with schemas.","toolsList":[]},"Validators":{"description":"The following is a list of tools that validate AsyncAPI documents.","toolsList":[]},"Compare tools":{"description":"The following is a list of tools that compare AsyncAPI documents.","toolsList":[]},"Others":{"description":"The following is a list of tools that comes under Other category","toolsList":[{"title":"AsyncAPI CLI","description":"One CLI to rule them all. \nThis is a CLI that aims to integrate all AsyncAPI tools that you need while AsyncAPI document development and maintainance. \nYou can use it to generate docs or code, validate AsyncAPI document and event create new documents.\n","links":{"websiteUrl":"https://www.asyncapi.com/tools/cli","repoUrl":"https://github.com/asyncapi/cli"},"filters":{"technology":["TypeScript"],"categories":["others","cli"],"hasCommercial":false,"isAsyncAPIOwner":true}}]},"CLIs":{"description":"The following is a list of tools that you can work with in terminal or do some CI/CD automation","toolsList":[{"title":"AsyncAPI CLI","description":"One CLI to rule them all. \nThis is a CLI that aims to integrate all AsyncAPI tools that you need while AsyncAPI document development and maintainance. \nYou can use it to generate docs or code, validate AsyncAPI document and event create new documents.\n","links":{"websiteUrl":"https://www.asyncapi.com/tools/cli","repoUrl":"https://github.com/asyncapi/cli"},"filters":{"technology":["TypeScript"],"categories":["others","cli"],"hasCommercial":false,"isAsyncAPIOwner":true}}]}} |
There was a problem hiding this comment.
just an update, CLI added, not much to review
| @@ -69,5 +69,9 @@ | |||
| "Others": { | |||
| "description": "The following is a list of tools that comes under Other category", | |||
| "toolsList": [] | |||
| }, | |||
| "CLIs": { | |||
There was a problem hiding this comment.
followed approach that all categories, even empty are here in manual file so people that add manually have easier life
| {"Code-first tools":{"description":"The following is a list of tools that generate AsyncAPI documents from your code.","toolsList":[]},"Code Generators":{"description":"The following is a list of tools that generate code from an AsyncAPI document; not the other way around.","toolsList":[{"title":"Sample Tool","description":"Tool for testing","links":{"websiteUrl":"https://akshatnema.netlify.app","docsUrl":"","repoUrl":"https://github.com/akshatnema/Login-Registration-project"},"filters":{"language":{"name":"Javascript","color":"#F2F1C7","borderColor":"#BFBE86"},"technology":[],"categories":["code generator"],"hasCommercial":false,"isAsyncAPIOwner":false}}]},"Converters":{"description":"The following is a list of tools that do not yet belong to any specific category but are also useful for the community.","toolsList":[]},"Directories":{"description":"The following is a list of directories that index public AsyncAPI documents.","toolsList":[]},"Documentation Generators":{"description":"The following is a list of tools that generate human-readable documentation from an AsyncAPI document.","toolsList":[{"title":"asyncapi-asciidoc-template","description":"Asciidoc template for the asyncapi generator","links":{"repoUrl":"https://gitlab.com/djencks/asyncapi-asciidoc-template"},"filters":{"language":{"name":"Javascript","color":"#F2F1C7","borderColor":"#BFBE86"},"technology":[],"categories":["documentation generator"],"hasCommercial":false,"isAsyncAPIOwner":false}}]},"UI components":{"description":"The following is a list of UI components to view AsyncAPI documents.","toolsList":[]},"DSL":{"description":"Writing YAML by hand is no fun, and maybe you don't want a GUI, so use a Domain Specific Language to write AsyncAPI in your language of choice.","toolsList":[]},"Frameworks":{"description":"The following is a list of API/application frameworks that make use of AsyncAPI.","toolsList":[]},"GitHub Actions":{"description":"The following is a list of GitHub Actions that you can use in your workflows","toolsList":[]},"Mocking and Testing":{"description":"The tools below take specification documents as input, then publish fake messages to broker destinations for simulation purposes. They may also check that publisher messages are compliant with schemas.","toolsList":[]},"Validators":{"description":"The following is a list of tools that validate AsyncAPI documents.","toolsList":[]},"Compare tools":{"description":"The following is a list of tools that compare AsyncAPI documents.","toolsList":[]},"Others":{"description":"The following is a list of tools that comes under Other category","toolsList":[{"title":"AsyncAPI CLI","description":"One CLI to rule them all. \nThis is a CLI that aims to integrate all AsyncAPI tools that you need while AsyncAPI document development and maintainance. \nYou can use it to generate docs or code, validate AsyncAPI document and event create new documents.\n","links":{"websiteUrl":"https://www.asyncapi.com/tools/cli","repoUrl":"https://github.com/asyncapi/cli"},"filters":{"technology":[],"categories":["others","cli"],"hasCommercial":false,"isAsyncAPIOwner":true}}]},"CLIs":{"description":"The following is a list of tools that you can work with in terminal or do some CI/CD automation","toolsList":[{"title":"AsyncAPI CLI","description":"One CLI to rule them all. \nThis is a CLI that aims to integrate all AsyncAPI tools that you need while AsyncAPI document development and maintainance. \nYou can use it to generate docs or code, validate AsyncAPI document and event create new documents.\n","links":{"websiteUrl":"https://www.asyncapi.com/tools/cli","repoUrl":"https://github.com/asyncapi/cli"},"filters":{"technology":[],"categories":["others","cli"],"hasCommercial":false,"isAsyncAPIOwner":true}}]}} |
There was a problem hiding this comment.
just an update, CLI added, not much to review
| @@ -1,18 +1,20 @@ | |||
| const { getData } = require('./tools/extract-tools-github'); | |||
| const { convertTools } = require('./tools/tools-object'); | |||
| const { combineTools } = require('./tools/combine-tools'); | |||
| const manualTools = require('../config/tools-manual.json') | |||
There was a problem hiding this comment.
I moved it here from combine-tools as it felt confusing for me that we read one of input data inside the helper function
There was a problem hiding this comment.
rest of changes is just related to it
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-1135--asyncapi-website.netlify.app/ |
| { | ||
| name: "CLIs", | ||
| tag: "cli", | ||
| description: "The following is a list of tools that you can work with in terminal or do some CI/CD automation" |
There was a problem hiding this comment.
came up with new category because there was no better one for AsyncAPI cli
| if (languageSearch.length) { | ||
| finalObject.filters.language = languageSearch[0].item; | ||
|
|
||
| //there might be a tool without language |
There was a problem hiding this comment.
in case of CLIs there is no language
There was a problem hiding this comment.
Means that there can be certain tools in list whose language is not defined, right?
| @@ -25,7 +25,7 @@ | |||
| }, | |||
| "filters": { | |||
| "type": "object", | |||
| "required": ["language", "technology", "categories"], | |||
There was a problem hiding this comment.
in case of CLIs there is no language, this is why I made it optional
| @@ -2,7 +2,7 @@ | |||
| "$schema": "http://json-schema.org/draft-07/schema#", | |||
| "title": "JSON Schema for AsyncAPI tool discovery file.", | |||
| "type": "object", | |||
| "required": ["title", "description", "maintainers", "links", "filters"], | |||
There was a problem hiding this comment.
yeah, maintainers are not used anymore
|
@akshatnema @magicmatatjahu added few comments to make it easier with review |
| for (const key in automatedTools) { | ||
| let finalToolsList = []; | ||
| if (automatedTools[key].toolsList.length) { | ||
| for (const tool of automatedTools[key].toolsList) { | ||
| finalToolsList.push(await getFinalTool(tool)) | ||
| } | ||
| } | ||
| if (manualTools[key].toolsList.length) { | ||
| if (manualTools[key] && manualTools[key].toolsList.length) { |
There was a problem hiding this comment.
What if automatedTools doesn't have key that is in manualTools? 😄 Because in current code we can "skip" some tools defined in the manualTools.
There was a problem hiding this comment.
We already have defined certain categories in the category list so if anyone adds a new category in manual-tools, it has to be updated on the category-list file first, because it is connected to frontend implementation also.
There was a problem hiding this comment.
if something that is not in category list is added to manual list, it is just ignored, which is good
if something is added to manual list, and category list is updated, then it automatically is in automated list
or
tl;dr - there will be no issues. The only reason I extended this if is in case there is something in category list, but was not added to manual list
There was a problem hiding this comment.
Couldn't this logic be made more complicated? 😆 But ok, you guys are more familiar with the implementations, so it's ok for me.
There was a problem hiding this comment.
Yeah, I agree it is quite complicated for me also. If don't revise it for months, I'll forget the logic behind this implementation 😅
scripts/tools/tools-object.js
Outdated
| for (let tool of dataArray) { | ||
|
|
There was a problem hiding this comment.
I think that code inside loop should be also wrapped by try catch, only to console log possible errors in code.
There was a problem hiding this comment.
I don't think it is needed. In case of errors other than validation we should throw error and not console log. And this is happening. In the end conversion function is wrapped in try/catch in place where it is called
There was a problem hiding this comment.
In the end conversion function is wrapped in try/catch in place where it is called
Where? I don't see any try/catch. I only see checking errors by validate function, but it's not a typical try/catch.
There was a problem hiding this comment.
Yeah, I agree with @magicmatatjahu, we should have try/catch block here and I got some errors on this part of code only. Basically, we aren't putting any error handling for axios function, so it would be better if we make a try/catch block there to get correct error log messages.
There was a problem hiding this comment.
Where? I don't see any try/catch. I only see checking errors by validate function, but it's not a typical try/catch.
I think @derberg is talking about the try/catch block used in scripts/build-tools.js file which applies to every function call made inside the functionality.
There was a problem hiding this comment.
It can be fixed in other PR, I don't want to block you guys :)
There was a problem hiding this comment.
I think @derberg is talking about the try/catch block used in scripts/build-tools.js file which applies to every function call made inside the functionality.
Aaa ok, thanks for clarification!
|
/rtm |
@akshatnema I opened a PR as I remember we agreed that it is of your scope for mentorship.
I decided to add YAML support now, next to JSON because when I was writing first file, it felt better to do it with YAML -> https://github.com/asyncapi/cli/blob/master/.asyncapi-tool