feat(asyncapi-generator-plugin): v3 asyncapi schema support + refactor to fix racing condition when writing files

[linas-ipxo]

Motivation

AsyncAPI have released v3 spec, so this updates the asyncapi plugin to support that.

Have you read the Contributing Guidelines on pull requests?

yes

Notes

This is quite large PR, although I don't see how/if I could split it up.

I started working on general v3 support, but found a bug in the process which manifested only with the new @asyncapi/parser version and/or the specific case described below. I'm still not exactly sure what causes it, but the code included here fixes that.

The bug only appeared when working with different versions of schemas at the same time - v2 + v3. For some reason the last version parsed would overwrite the previous version's frontmatter.

E.g. if the list was [v2, v2, v3], then v3 frontmatter would be generated first, but then would be overwritten by any of the v2. Same would happen if it was the other way around - [v3, v3, v2] - v2 frontmatter would be overwritten by v3.

If only single version would be provided - [v2, v2, v2] or [v3, v3, v3] - everything would be parsed and written correctly.

So something in the new parser affects something, but again - i'm not sure exactly what.

The solution for this, in this PR, is that parsing and writing of files are two discrete actions, one after another. So it first parses all files, collects the info, then writes them all out.

Additionally, during debugging of all this, i tried to simplify my workflow, and came up with a way to run the plugin directly instead through the main project. I left the code in, because it doesn't seem to break anything, but possibly will help in the future as well if any issues arise. I saw there is separate script in scripts/generate-catalog-with-plugin.js, but it's hardcoded and limited.

As for the v3 support itself, it's all backwards compatible. The code changes how the information is gathered from the parser. One possibly breaking change (not sure) is dealing with anonymous message names. My code does some assumption based handling, as did the previous code, but slightly different.

As I'm quite new to TypeScript and related, let me know if something is wrong/bad with no hesitation. I tried reaching out on Discord while working on this, but that seems pretty much dead..?

[changeset-bot]

🦋 Changeset detected

Latest commit: 6534cc2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@eventcatalog/plugin-doc-generator-asyncapi	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

2 Ignored Deployments

Name	Status	Preview	Comments	Updated (UTC)
eventcatalog-docs	⬜️ Ignored (Inspect)	Visit Preview		Jan 16, 2024 9:44am
eventcatalog-example	⬜️ Ignored (Inspect)	Visit Preview		Jan 16, 2024 9:44am

[boyney123]

thank you @linas-ipxo for the effort here, sorry it's taken me so long to get round to this.

I reviewed the code, had a few conflicts I fixed, but looking good to me, tests seem to be passing, and your code seems to make sense to me! If anyone has any issues we can review those.

Thanks for this, going to help others loads!