Apicurio-studio: Able to support AsyncAPI standard in editor

I'd love to see an Apicurio visual editor for AsyncAPI. Right now this project doesn't have the engineering bandwidth for such an effort. :(

@EricWittmann thanks for response. I will try to find some time for work on this feature if it will not be so difficult...

Well I think adding support for AsyncAPI is a huge amount of work. The first task would probably be to implement a parser/model layer for it. For OAI I've done that here:

https://github.com/apicurio/oai-ts-core

So that's probably a good place to start - perhaps a new repository like asyncapi-ts-core.

If you're up for that sort of thing that'd be great! I'd need to start thinking about the best way to get asyncapi support into the rest of Apicurio. There are a number of considerations across the various UI pages.

For what it's worth, AsyncAPI is starting to pick up some additional steam. So providing support for it in Apicurio is climbing up the priority list. :) No ETA or anything like that YET - but hopefully we can start making some progress in this area.

Good to hear this news, @EricWittmann , thanks. I would like to participate, if will find enough time.

FWIW, we now have a parser for AsyncAPI 2.0.0. We've been discussing on migrating to Typescript. It'd be great to have a list of tasks of what needs to be done in order to have AsyncAPI in Apicurio. We may be able to help :)

That's interesting, @fmvilas - thanks for the pointer. We've actually built our own unified data model implementation for AsyncAPI and OpenAPI here: https://github.com/Apicurio/apicurio-data-models

That library is written in Java and is transpiled into Typescript so we can use it both in our back-end and also directly in our UI. It also has various features like full visitor support, a simple operational transformation engine, etc...

On to the more interesting part of your comment - tasks that need to be done in order to have AsyncAPI in Apicurio. :) :) I think the big thing right now is probably editor support. Ultimately I would like to have feature parity with our visual OpenAPI editor (which includes validation and concurrent editing support). However, I think a nice (perhaps temporary) contribution in the short term would be to integrate the existing text-based AsyncAPI editor into Apicurio. That'd be very cool and would go a long way. I could see a future where the text-based editor and the visual editor are both supported options. I've actually had one community user ask for that - their senior developers didn't like the visual editor and instead wanted a text editor. Go figure.

Other than the editor, I'd have to think about the list of tasks. But everything else would be incremental on top of the editor (e.g. project generation).

On to the more interesting part of your comment - tasks that need to be done in order to have AsyncAPI in Apicurio. :) :)

I hear you :)

Well, as you said, let's start with something easy/easier. I will let you know as soon as we have some bandwidth to collaborate. Thanks!

Collaboration would be awesome, for sure. In the meantime, if you have some documentation around how to embed the AsyncAPI editor into other applications, I could probably knock out something interesting as a POC pretty quickly.

I'm referring to the editor found in the playground here: https://playground.asyncapi.io/

I haven't looked into that yet - so am not sure whether it has been built to be leveraged easy within other applications, but if so then hopefully it's not difficult to import and use. That would go a long way towards claiming (at least initial) AsyncAPI support within Apicurio Studio.

Hi @EricWittmann ,

I spend some time investigating today what would be the cost of adding graphical editor for AsyncAPI and come to the beginning of a result lately. See the screenshot below - I've recreated the same structure as OpenAPI and added the code editor we already have so we already have feature parity vs what we have today. I've started from the AsyncAPI example I previously added.

Few thoughts and questions I'd like to share:

• 1st on the implementation side: new editor component was already present and I pursue following this by duplicating existing components into their AsyncApi* counterpart. Most of the time just replacing OasDocument by AaiDocument, that is not that elegant ... However I've just scratched the surface and there will be more important differences between the 2 specs ... Would you prefer keeping this way and having 2 independent sets of components or trying to mutualize even if there will be a lot of if document.isOpenApi() or if document.isAsyncApi() along the code ? What do you think ?

• 2nd on the process. As you said before, it may be a big effort ... Not technically difficult but long and meticulous ... So I don't think I will have the patience nor it is feasible to implement the whole spec editors before committing anything. I'd rather see that as an iterative task where I could fill some pieces starting with high priorities (Channels, DataTypes, Messages, Examples ;-)) then going to lower priorities (Servers, Traits and so on...). What do you think ? Would it be ok to split the implementation on many Pull Requests ?

I'd really be happy to help as you may have seen that Microcks now supports AsyncAPI mocking (and testing in a few weeks). So it could be a game changer to have Apicurio support that and allow to cover the major styles of modern API specs.

cc @fmvilas ;-)

First of all - congrats on the addition of AsyncAPI support in Microcks! I did see that was added recently.

I have a couple thoughts about this. First is that I think it might make sense to try and get the AsyncAPI Playground editor embedded into Apicurio Studio if that is technically "easy". :) That would be a quick win and would give us reasonable "beta" support for editing AsyncAPI documents in Apicurio Studio.

After that, we could focus on getting a visual editor created.

(1) As for your question about implementation - I think duplicating the components and modifying them to fit AsyncAPI is the right approach in the short term. The reason is that it's easy enough to refactor later to share components across the two editors, but more than that is that we'll be re-implementing the entire Studio UI in React at some point. So any major efforts we make in the current Angular implementation would be wasted. Better to do something fast since it'll have to be redone later anyway.

(2) I agree that the effort is not technically difficult but is long and meticulous. :) I think it makes sense for the implementation to be split into multiple PRs - hopefully we can break up the work across multiple contributors too.

@fmvilas Is the editor found in the AsyncAPI Playground open source (I'm assuming yes) and also able to be easily integrated into other tools like Apicurio Studio?

(if yes any pointers to howto documentation would be awesome)

Thanks @EricWittmann !

I had a quick look at the AsyncAPI playground first but it seems to have server-side components in NodeJS. So I was thinking that the integration would be not that easy ... that's why I explore the editor way ;-)

I should be able to spend some more time on it by the end of the week... If it's ok for you, I'll try submitting a first PR bu the beginning of next week. It should be possible to have the main informations editable (Version, Contact, License and Tags) as well as a read-only preview of the Channels on the left-side column.

It's open source, you can find it here. However, we're working on a much better one with autocompletion, errors reported in the editor itself by "underlining" the wrong lines and columns, etc. It's actually the one seen on AsyncAPI Hub, which will eventually replace the Playground. This one is not yet open sourced but will be very soon, before the end of the year for sure, and it's done in React using Monaco editor (the editor powering VS Code).

But given that you're using Angular at Apicurio Studio, I'm not sure it will be helpful. I heard it's possible to combine React and Angular but honestly never tried.

Thanks @fmvilas - we're ultimately going to convert to React as well (that's in progress). Does the new AsyncAPI editor require any server components or is it purely client-side React? And is it intended to be embedded in other projects?

We never thought others could be interested in embedding it but should be easy to do because it's already an isolated component, so yeah, we can make it easily embeddable. The component is purely client-side React because Monaco doesn't support server-side rendering.

First PR for bootstrapping the editor on its way! See #1280

And here's another one at #1285 ;-)

Very soon we should enable AsyncAPI support by default (the feature is currently off by default I believe).

Hi @EricWittmann and all!

Here's another one bringing : Operation, Message, OperationTrait and MessageTrait support. See #1313 ;-)

All the details of each concept are not yet fully implemented as a graphical form but the framework is there.

Hi all!

Found some time this week-end for some new enhancements: here's another PR #1382.

We can now create new Operation, set Payload and Headers type as well as providing Examples (useful now that we can directly mock AsyncAPI with Microcks connector 😉 )

@EricWittmann how do you enable it?

For the apicurio-studio-ui container you need to set the APICURIO_UI_FEATURE_ASYNCAPI environment variable to "true" (as string, not boolean), @alizard0 .