A couple of months ago we released the visualiser into the Studio, and from initial feedback, it seems that the community quite like it and find it valuable.

It would be good to understand what else we can do here to make it better?

If you have any ideas or thoughts please share them so we can explore and maybe start building them!

Ideas

1. Allowing the user to create AsyncAPI file from Visualiser (Drag, Drop Nodes and Connect them)

This idea came from @magicmatatjahu but the thought of allowing users to use this tool to build their AsyncAPI file, but using nodes and drag and drop interface.

Users will be able to create subscriber, publisher, and also application nodes and connect them together. When connecting them you will probably be prompted to enter various details about the node type you are connecting/adding.

I will add more ideas as time goes on

Describe the bug

The hosted AsyncAPI studio website freezes regularly when editing AsyncAPI .yaml files. If the website recovers from freeze the default yaml file is loaded. The current WA is to store the edited file into a local yaml file every few seconds. Of course this is quite annoying. Actually this makes it impossible to use the website ATM.

How to Reproduce

Open https://studio.asyncapi.com in Firefox and edit a file with approx. 100 lines.

Expected behavior

We should implement this change on Studio too: asyncapi-archived-repos/playground#21

Right now, we're building the errors manually in many places, which is error-prone and leads to a lot of duplicated code.

It would be great to add methods to deal with error creation, such as:

const { organizationInvitationsOrgNotFound } = require('../error');
throw organizationInvitationsOrgNotFound(invitation.organizationId);

which internally, it would be something like:

class HubError extends Error {
  static organizationInvitationsOrgNotFound(orgId) {
    return new HubError({
      ...
    });
  }
}

It is common to start drafting something on your own personal project and then move it to a team-owned one.

As we have in all other repos, we should initiate all-contributors.

Describe the bug

“Funny” enough we were caught by the same bug in our project @bump-sh, and wanted to test it in the AsyncAPI studio to discover the bug is also present here. When providing a null object as value of a server binding object (or channel binding object), the editor crashes.

How to Reproduce

Add bindings to a valid server object, add an entry with sqs: (for instance) and wait <1 sec for the crash to happen.

Servers object used to crash:

servers:
  test:
    url: example.org
    protocol: https
    bindings: { sqs: }

Expected behavior

• The editor shouldn't crash 😅
• Not sure if its an invalid specification error (the spec doesn't seem to disallow a null object as a binding object value)?

Sorry I couldn't dig more into the code to try to provide a bugfix. Maybe later if the bug is still present.

Reason/Context

AsyncAPI html-template renders Markdown on fields such as info.description. However, the current version of the Event Visualizer doesn't render Markdown.

Example:

Using the Streetlights MQTT example, which contains valid Markdown in info.description.

We can see the documentation is properly rendered:

However, Markdown is not rendered when in Events Visualizer:

Description

This feature request is just about supporting Markdown rendering on the Events Visualizer.

At the moment we have only two main panels + navigation: navigation on the left, and the panel with the editor (middle) and the panel for displaying the documentation (and visualiser) on the right. This is enough for now because we don't have the ability to add plugins (aka modules) to our studio. However the current solution will not be easy to use new things and does not give a really big freedom for the user (in the future, when we will add more stuff to the Studio).

A very good solution would be to use the idea like in VSC - we have navigation on the left, which opens our content on the right in the form of tabs and split panels, where we can open two parallel panels, for example editor + html preview or 2 editors.

Each panel would have its own tabs and the content in the navigation would change depending on where the user focuses his/her attention, i.e. in which editor he/she changes the value - just like in the VSC. We can then, for example, add a context for panel/tab like in our CLI, which would specify which specification to render to html etc.

What do you think?

Description

We used to have Google Analytics hardcoded (see #13). However, some people may not want to use it so it's better if we make it a plugin instead.

Implementation suggestion

1. Go to src/pages/_app.js file and make it trigger a new kind of event on the render function. For instance, something like a page:render event. Make sure this event is only triggered on the client-side render.
2. Make the plugin subscribe to the event and trigger an initialize and pageview call when a new event comes in.

Hints

The code for triggering/subscribing to events is on src/lib/events.js. However, this library was created for the backend and it imports the config lib, which may contain secrets. If we use the events lib on the frontend, these secrets may be exposed on the browser. Watch out!

http://studio.asyncapi.com/

Examples:

It would be cool to enable Studio to validate an example payload against the message schema.

This would enable quick prototyping and move into a direction of one tool to rule them all, as currently it is possible to use third party validator like https://www.jsonschemavalidator.net

Reason/Context

Please try answering few of those questions

• Why we need this improvement?
  It would be beneficial to developers to be able to run this locally and internally within organisations.

• How will this change help?
  Pushing the docker image for every new release to docker hub

• What is the motivation?
  Swagger Editor also provides this https://hub.docker.com/r/swaggerapi/swagger-editor/

Description

Please try answering few of those questions

• What changes have to be introduced?

On release builds the versioned docker image would be built and pushed to docker hub

• Will this be a breaking change?
  no

• How could it be implemented/designed?
  as part of the GibHub build

Describe the bug

If I copy this snippet from https://github.com/asyncapi/avro-schema-parser

asyncapi: 2.2.0
info:
  title: Example with Avro
  version: 0.1.0
channels:
  example:
    publish:
      message:
        schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
        payload: # The following is an Avro schema in YAML format (JSON format is also supported)
          type: record
          name: User
          namespace: com.company
          doc: User information
          fields:
            - name: displayName
              type: string
            - name: email
              type: string
            - name: age
              type: int

into https://studio.asyncapi.com/ I get error N[String(...)] is not a function.
If I download the studio locally and past the same snippet, it works.

How to Reproduce

see above

Expected behavior

No error

We have integrated linter (eslint) in other repositories in our organization. We should do this also in this repo, for increase DX.

Reason/Context

I would have assumed that any changes to documents would automatically be saved as there are no other indications, that you have to manually perform this action using a shortcut cmd + s.

Once this is done, we should remove the HTML template and start using the React component. This has many benefits. For instance, we can do everything on the client-side.

Reason/Context

Many backend devs are not using Node.Js and are forced to install Node.js to beeing able to use the app locally.

Description

Would be great if one could simply use a Tauri or Electron based app.

Reason/Context

Hey!

I have been working on a visualiser tool that uses React Flow to render an AsyncAPI file.

Here is a screenshot of the kind of thing working so far.

I would like to add this into the Studio, and maybe in some different phases.

Maybe for now, I will add just the diagram:

• Given the AsyncAPI file it will render the diagram (read-only for now).

How will this help

I think it's an additional tool that will help people visualise their AsyncAPI file.

Next Steps

Would be great to understand how I can add this into the Studio. I think I will use the service files already there which look great! I just need to figure out a place this can live?

I think long term it would be good to package it up maybe as a React component etc and maybe a Plugin of some sort, but for now we can hard code it into the project?

@magicmatatjahu What do you think?

Another route in the project that will just render this on another page or try and get it rendering on a page somewhere that exists?

I'm going to spike out some ideas and proposals so will post here when I do.

Currently, the plugins source code is located at a plugins folder on the root directory of the project. They should have their own repo, either one repo for each or a plugins repo.

Whenever we render an error page, it links to a documentation page where you can find more information about the error. This pages don't exist yet. That's what this issue is all about.

In #80 proposal was proposed to create a (server) API that would later be used by the Studio for things that cannot be done in the browser. Most of our tools are isomorphic, but e.g. generator still need to run a NodeJS environment. Issue is opened to discuss how this API should look like, what it should offer, in which technology/framework it should be written and in which way it should be distributed.

@jonaslagoni @derberg @fmvilas @smoya You should be interested in this topic :)
@BOLT04 If you want also add comment, feel free, but I'm not forcing anything.

Closed issues (related to old implementation of the Studio) but are related to the server API and should be consider to implement:

• #9
• #12
• #8 - plugins for server API
• #14 - Google Analitycs plugin - mainly in front-end app, but here it can be also used.

Reason/Context

@magicmatatjahu has been working hard on getting our new studio up and running, and it's looks amazing.

With the ideas we have coming to this application will grow with features and functionality.

I think we might want to accompany this application with some nice docs 👀

I just come across this website https://developers.apideck.com/ and something like this would be great for our Studio (I think).

A place people can find

• How to install it
• What features it provides etc

Think it would be great!

Any thoughts? cc: @magicmatatjahu @alequetzalli

Reason/Context

I am wondering if the icons on the navigation properly explain what the window is that corresponds to it. I suppose users who are frequent on the studio might know from learning the system, but in order to make it easier for new users to quickly understand the system, I am proposing that we add tooltips on hover of each navigation item so there are proper labels for each window pane.

I think in addition to this, there might be a way where we can make the navigation items that are active have a more obvious style than just the white color and border on the left side. I feel that sometimes the white border on the left can get lost depending on where you have your window positioned on your computer, especially because someone may have the window bleeding off the left side and might miss the white border entirely.

I can create a mock up for these ideas soon and share it on this issue, but just wanted to add in this issue ASAP.

Reason/Context

When going to https://studio.asyncapi.com/ the first thing that comes up for me (as new user) is I can upgrade my AsyncAPI file.

I think our default AsyncAPI file should be the latest one (2.2.0 version), so users don't see this straight away.

Screen of what I see

Reason/Context

At the moment when you have the sidebar and the documentation open, clicking on a message, operation etc will take you straight to the place in the docs.

I think it would be a nice touch to have the nodes in the flow diagram highlight (maybe blink animate) when clicking on these nav items.

So if the user has this nav bar open....

Clicking on the items whilst looking at the flow diagram will highlight the nodes.

The current studio is written using the NextJS framework. The application consists of several parts (because it's not the plain NextJS app):

• server which is running by ExpressJS. Its role is to communicate with the database, save AsyncAPI documents, generate HTML Template as well as Markdown Template etc.
• "Static" UI - the part that communicates with the server and is the UI for it, the part where you manage your user account, save your documents etc, create organizations etc. - Something like https://swagger.io/tools/swaggerhub/ but for AsyncAPI. Of course this part is not that extensive, it has only a few functionalities.
• Dynamic UI - part with editor and where HTML template is rendered.

The most important part for us is the third part, which is related to the editor and displaying the documentation in various way.

The first part currently exists, but for some reason we can't and don't even want to manage and store data about users, their organizations and the documents themselves. The only thing we would need from the server would be a few endpoints to generate the templates and save it to the user's disk. Just that.

Due to the requirements, the 1st and 2nd part "completely" falls out. That leaves only 3. Personally, I don't see the point of using NextJS where we wouldn't use any of its advantages, i.e. SSR (Server Side Rendering), or SSG (Static Site Generation). Studio should be a frontend application that performs all operations on the client side. Most of our libraries that we currently use (and will use, like diff etc.) in the client-side studio are isomorphic (you can use them client-side and server-side), so that's another reason to remove NextJS. Of course I still see the point of having a server, but for things like using our generator that we can't use on the client side. But under this case, a simple SPA application, which communicates to the simple server setup next to it, is enough for us, without any SSR.

I know that the current studio also has the ability to define plugins, but... they only work properly on the server side. So they only work for the first two parts of the Studio, the Server and the Static UI. You can't change or add new things to the editor itself, because initialization of these plugins is at the Node level, not at the browser level. You can read more about this problem here -> #37 (comment)

Treating the studio itself like a SPA will additionally allow us to publish this as a simple react component -> asyncapi/asyncapi-react#146

Here I have to sorry all ofyou, because I made a mistake and didn't ask anyone in the community if removing NextJS makes sense. I saw so many problems that I thought I was doing the right thing, but AsyncAPI is a community-driven organization, so I apologize.

What do you think about this? Maybe I'm completely wrong and it makes sense to leave the NextJS.

Also, below is a video that shows what I did while rewriting the studio. It's a pure SPA application.

https://streamable.com/9m607y

Describe the bug

Current version of the Studio can't load http://json-schema.org/draft-07/schema when deployed in production.
This causes a warning on the editor such as:

How to Reproduce

Go to https://studio.asyncapi.com and load any AsyncAPI File.

Expected behavior

Warning should not be there.

The error is due to the fact the app is trying to load a http resource when the whole HTML has been loaded through https. This is illegal. In fact, the developer console is pretty clear:

​ Mixed Content: The page at 'https://studio.asyncapi.com/js/monaco/yaml.worker.bundle.js' was loaded over HTTPS, but requested an insecure resource 'http://json-schema.org/draft-07/schema'. This request has been blocked; the content must be served over HTTPS.

It seems we can provide a valid schema via monaco-yaml settings: https://github.com/remcohaszing/monaco-yaml/blob/main/index.d.ts#L4-L25

Reason/Context

Current nav bar buttons don't provide any alternative text. This makes it hard to know what button does what.
The issue goes further because it means screen readers won't do their job, meaning Studio can't be used on all its potential by people with visual impairments.

Description

I would suggest we, at least, add both <title> and <desc> elements to our inline svg's (the buttons are) so they act as alternative text.

More info here https://css-tricks.com/accessible-svgs/

Reason/Context

The idea of this proposal is to add a "Share" button (or any component that fits) allowing the user to generate a URL that can be shared with anyone, and that will open the Studio but with the desired spec file loaded, representing that file in a certain moment in time, and loading any Studio setting the person who shared configured by then as well.

Sharing a URL that points to a reproducible Studio state is useful for several scenarios:

• Users can share AsycnAPI files without having to host them somewhere (like GH gists, etc), plus the fact you have all Studio amazing features out of the box.
• Tools that generate AsyncAPI files (like Chatbot, CLI...) could give a URL as a result instead of generating the code, or printing to stdout, etc.

You can see an example of such feature in Go (language) playground: https://play.golang.org/p/ENxYVMoY9VZ

Description

Let's see first a couple of mocks to illustrate the idea:

This is not as trivial as it might seem. I'm gonna add some context:

The first idea was to just accept all state (spec file, settings...) encoded as base64 in a query param. Then the studio will decode that value to obtain the state and draw it.
The problem with this approach, as @magicmatatjahu stated, is that each browser have their own limitations on the URL length (also with the length of each query parameter). Most of them, limiting the full URL to 2048 chars which is not a lot. E.g. Streetlights MQTT example has ~6000 chars already.

With such limitation in place, there are not a lot of solutions for solving this.

Proposal

TL;DR: Storing the state in an external storage. Downloading it later and import it into the Studio.

• Generating the URL will require passing the current state (AsyncAPI file + any settings) to an external service, which will generate a UUID (either based on the content like SHA256, or a UUID v(x). To be defined) and store the given state in a Storage (external database, cloud storage, etc). That UUID will be returned to the Studio and will be the only identifier needed to construct the shareable URL. Optionally, to use (or maybe create our own?) a URL shortener service for making the URL shorter.
• Loading a shared URL will require a call to an external service (same), which from a given UUID, will fetch the state from a Storage (external database, cloud storage, etc) and return it to the Studio, which will load such state.

Note: Other services like Chatbot could also use this service.

Obviously, this is only the big picture. Details should be clarify. Further investigation should be done, especially around the following topics among others:

• What storage should we use? How can we get budget for it?
• Shall we use https://github.com/asyncapi/server-api as server for making the sharing logic? Or rather a separate microservice that just owns such responsibility?
• Security concerns. Only available to our services.
• Monitoring seems now like a must, as it is a server giving a functionality to a public hosted tool. High Availability is a must as well.
• Which protocol to use? GRPC?
• Etc.

cc @magicmatatjahu @derberg

Description

@jonaslagoni suggested to have PR's preview like we have in website repo. As far as I remember, we can have several repos linked to the our Netlify Open Source free plan, so we should enable preview in this repo.

Reasons

To Improve DX in PR's review.

cc @derberg @jonaslagoni

Reason/Context

I'm lately advocating for using Studio whenever I want to add a link to an AsyncAPI file in a Markdown file such as Readmes. Thanks to the ?url=<url-of-file> query param, Studio can load most of files (yes, not all of them, see #127).

I think it would be awesome to create a new design for a button that says "Open with Studio", with the AsyncAPI logo on the left or similar.

Description

To design a button that says something like "Open with Studio", with the AsyncAPI logo somewhere that people can use for linking to AsyncAPI files in their Markdown/HML files.

Some examples:

cc @mcturco @alequetzalli @boyney123

Reason/Context

We still have the Event Gateway in development, and I was speaking to @smoya a couple of weeks ago, and I believe the gateway will/does provide a websocket url.

I believe the Gateway acts like a middle man between events and brokers (at the moment only supports Kafka). The WebSocket is used to pass any key information to anybody that wants to listen (validation issues etc).

I think it might be nice if the Studio supported integration into this WebSocket?

Maybe as an optional feature (for example if the ENV var is set for the feature/websocket url) then the feature can be there.

What will the feature do

I guess it really depends on the contract from the event-gateway, but it can be used to help people see any validation issues they may have, payloads going across systems etc......

(We would have to explore this more).

But I believe a tool that consumes this WebSocket URL would be great.....

Alternative

We don't put it in the studio but just have another application that's sole purpose is the event-gateway-WebSocket listener or something.

Would love to know your initial thoughts? @magicmatatjahu @smoya

Describe the bug

The "beta" label near the logo became black and it's almost invisible.

How to Reproduce

Have a look at https://studio.asyncapi.com

Expected behavior

I was expecting it to be visible. I think it used to be cyan or white 🤔

Implement functionality to convert from AsyncAPI 1.x to 2.0.0, like in the Playground.

Reason/Context

Comes from #141 (comment)

UpdateState is used everytime an update should happen on a file.
Right now, UpdateState contains a full version of the updated file.
As far as the update is done locally, lag should not be a problem. However, asyncapi/cli#104 (and maybe future features?) introduce the possibility of modifying files remotely, meaning the UpdateState will flow through internet.
Passing a full version of the file every time it is updated it is not ideal. This will introduce lag, which will translate into a not so good user experience.

Adding the possibility to create a UpdateState with a diff of the file should be possible.

Description

Adding a new field in UpdateState, called for example updateType where it describes the nature of the update: full content or diff.

When diff, we could expect a json diff patch (sent by CLI in this case, or generated by the Studio).
https://github.com/benjamine/jsondiffpatch could be used for generating and applying the patch.

Filter by project is not working properly.

Examples on HTML template documentation are not highlighted.

Reason/Context

At the moment Studio only supports one application, but often you design multiple applications that are interacting with each other. So introducing something like a "project" could be really useful.

Description

We can still do local savings to the browser, it just enables us to integrate something like Cupid and other tools 🙂

Reason/Context

The studio is now hosted on the internet which is great!

People will be coming to this from all over, and I wonder if it would be a nice feature for them to select a template or real-world example before they go into the studio.

I made a video to explain what I mean and also how it would kinda work (https://asyncapi.slack.com/files/U020GN9C6FM/F02KDGTE1L2/studioexamples.mp4)

Screenshot

When will it be shown

• When users come new to the studio
• When users come from the web (maybe).

Why we need this?

I just think it would give users the ability to explore AsyncAPI more, rather than be thrown a default template on load.

Reason/Context

In some hosting scenarios (e.g. Docker Compose, Kubernetes) the container might not be exposed at the root path of the host.

AsyncAPI Studio does not handle this well at the moment:

I think it would be great to support this so that people can easily host the Studio in whatever environment they like.

Describe the bug

Unlike the events visualizer button, clicking on the new templates button opens a new view that covers the whole studio (except the nav bar). When clicking then on any other button like the code one , doesn't quit the examples view.

The only way to close it is to click again on the same examples button, which is not a 100% expected behavior because it is quite inconsistent with the rest.

How to Reproduce

See the following video:

Expected behavior

Either examples view shows as a popup, or either just as a side view (as the events visualizer, code examples, etc), or we improve the navigation so on any click in any button will close the examples view.

Reason/Context

Current Studio picks up a JSON Schema from https://github.com/asyncapi/spec-json-schemas based on the asyncapi field.
This is valid for most of the users but I wonder if we could allow users to manually enter a URL of a valid JSON Schema (AsyncAPI one) so it can be used for validating.

The reason is that I find it useful for testing changes on the spec that are not yet fully merged.
I know the use case is very limited, but wondering if we could easily do that.

Description

Allow setting an external JSON Schema URL so it can be used for validating the document. It doesn't have to be in the UI, maybe a query parameter such as ?schema=<url> would be enough.

I'm on the highest plan possible without any restrictions. I can create multiple orgs but when I do it, the new orgs are created as "free" plan.

Reason/Context

The introduction headline does not really make sense, as what it refers to is the information 😄

Support customization of the base URL using headers like Playground does here: https://github.com/asyncapi/playground/blob/master/src/server/routes/html.js#L23.

Reason/Context

Description

Please try answering a few of those questions

• What changes have to be introduced?
  • Add tooltip to sidebar icons and visualizer icons
• Will this be a breaking change?
  • No

Screenshot

The socket-client.service.tsx file does not have tests. We should add them. The file in question is here: https://github.com/asyncapi/studio/blob/master/src/services/socket-client.service.tsx.

OpenGraph Studio issue

Reason/Context

Thanks to the ?url=<url-of-file> and ?base64=<base64-encoded-doc> query param, Studio can load most of files (yes, not all of them, see #127). I expect users will use that to share their AsyncAPI docs.

Whenever a link to Studio (with or without those query params) is pasted into social media (Twitter, Linkedin, Facebook, Slack...), the preview image is this one:

It is a great pic, however it says nothing about the file being shared.

What if we could dynamically generate the preview image based on the file being shared? For example, the title, description and some stats could be shown.

I created a POC based on https://github.com/vercel/og-image (deprecated atm), available in my fork (It's just a POC) which is a server that generates dynamic images for being used on Open Graph image meta tags. This works by generating a dynamic HTML, making an screenshot of it through headless Chromium, and serving the resulting image.

The server accepts a ?base64=<base64-encoded-doc> query param, and generates an image that contains the AsyncAPI doc Title, Description, number of servers, channels and messages.

Despite the horrible design, the service is able to generate the following:

Based on the following AsyncAPI doc:

asyncapi: '2.2.0'
info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signups
channels:
  user/signedup:
    subscribe:
      message:
        $ref: '#/components/messages/UserSignedUp'
components:
  messages:
    UserSignedUp:
      payload:
        type: object
        properties:
          displayName:
            type: string
            description: Name of the user
          email:
            type: string
            format: email
            description: Email of the user

Studio will need to modify the og:image tag so it points to this new service.

<meta property="og:image" content="http://<service-url>/*.png?theme=light&base64=YXN5bmNhcGk6ICcyLjIuMCcKaW5mbzoKICB0aXRsZTogQWNjb3VudCBTZXJ2aWNlCiAgdmVyc2lvbjogMS4wLjAKICBkZXNjcmlwdGlvbjogVGhpcyBzZXJ2aWNlIGlzIGluIGNoYXJnZSBvZiBwcm9jZXNzaW5nIHVzZXIgc2lnbnVwcwpjaGFubmVsczoKICB1c2VyL3NpZ25lZHVwOgogICAgc3Vic2NyaWJlOgogICAgICBtZXNzYWdlOgogICAgICAgICRyZWY6ICcjL2NvbXBvbmVudHMvbWVzc2FnZXMvVXNlclNpZ25lZFVwJwpjb21wb25lbnRzOgogIG1lc3NhZ2VzOgogICAgVXNlclNpZ25lZFVwOgogICAgICBwYXlsb2FkOgogICAgICAgIHR5cGU6IG9iamVjdAogICAgICAgIHByb3BlcnRpZXM6CiAgICAgICAgICBkaXNwbGF5TmFtZToKICAgICAgICAgICAgdHlwZTogc3RyaW5nCiAgICAgICAgICAgIGRlc2NyaXB0aW9uOiBOYW1lIG9mIHRoZSB1c2VyCiAgICAgICAgICBlbWFpbDoKICAgICAgICAgICAgdHlwZTogc3RyaW5nCiAgICAgICAgICAgIGZvcm1hdDogZW1haWwKICAgICAgICAgICAgZGVzY3JpcHRpb246IEVtYWlsIG9mIHRoZSB1c2Vy" />

The preview image would then look like (note that https://shaggy-stingray-56.loca.lt/ was a local tunnel to my localhost serving a simple html with the og-image tag):

By the way, all of this could run on serverless functions such as the Netlify functions (which are AWS Lambda) available in free tier :)

Description

Here is a sequence diagram showing the big picture of the flow a request made by an Open Graph crawler (crawlers used for querying the open graph image whenever you share a link) will follow:

sequenceDiagram
Open Graph Crawler->>+Studio: /?base64=<encoded_doc>
Studio->>Studio: Set og:title, and og:description metatags. Set og:image to <og-generator-service>/generate.png?title=foo&description=bar&operations=4&servers=2 
Studio->>-Open Graph Crawler: Pre-rendered Studio HTML webpage
Open Graph Crawler->>+OpenGraph Generator: <og-generator-service>/generate.png?title=foo&description=bar&operations=4&servers=2 
OpenGraph Generator->>-Open Graph Crawler: og-image.png

Note that, as explained in this comment, we would need to configure pre-rendering in Netlify for doing the og:image content URL replacement on each request made by a crawler.

Alternatively, whatever technology we use (for example NextJS), the flow for rendering the Studio page would be something like the following:

flowchart TD
    A[User] --> B(https://studio.asyncapi.com)
    B --> C{contains ?base64 or ?url}
    C -->|No| D[Static rendering]
    C -->|Yes| E[Dynamic rendering]
    E --> F(Parsing AsyncAPI doc + etc)

In case the image can't be generated due to whatever reason, the default AsyncAPI Studio should be served instead: https://studio.asyncapi.com/img/meta-studio-og-image.jpeg

What you will need to do

Note that the design of the Open Graph image card is also part of this task. Ask @Mayaleeeee for help on this (Thanks! 🙌 ).

Prerequisites

1. Fork Studio.
2. Deploy it to your own Netlify free account. I recommend you to do it via Netlify’s website UI and not via Netlify CLI. With few clicks your site will be configured to be deployed on each push to the branch you specify.
3. Enable Prerendering in your new Netlify site. This will allow web crawlers (such as the ones used for fetching the OpenGraph meta tags) receive a fully rendered version of the website, including content loaded by Javascript.

Work to do

1. Create a new Github repository where your Open Graph image generator service will be tracked.

2. Create then a new service that exposes an HTTP API that generates an Open Graph image based on few query params (use the names you want, the following are just suggestions):

   1. doc_url: a URL pointing to a raw AsyncAPI document.
   2. doc_base64: an AsyncAPI document encoded in base64.

   Some hints:

   • You will need to use the AsyncAPI Parser-JS to parse your document and extract the data you need from it
   • In order to generate the image, you can use @vercel/og package. (og-image is deprecated now). Documentation on how to use it is available here. Alternatively, if that package is not compatible in a non-vercel world, you might want to take a look to https://github.com/vercel/satori, which is what that package uses under the hood.

3. Deploy this new service somewhere. I recommend you to deploy it via Netlify Functions. Or even better if we can get it as a Netlify Edge Function (support of npm packages is still experimental) since I believe we will be able to implement a caching mechanism easily.

4. Once we have a public URL of that service, include a Javascript code somewhere in the Studio website that modifies the og:image meta tag content to point to the new service URL including the doc_url or doc_base64 query param with the right content. That will be the trick that will make the OpenGraph image shown dynamically based on such parameters.

5. Performance is a must. Both serving the Open Graph tags + generating the image should not take more than few secs (~3), otherwise crawlers will timeout (for example, Slack's crawler timeouts at 5 secs)

6. Investigate about caching. If hosted as a Netlify function, I believe we could just trust in cached responses. See https://docs.netlify.com/platform/caching/#supported-cache-control-headers. Otherwise, we could give a try to Netlify Blobs and store each generated image using the base64 hash (or a reproducible and atomic hash) so every new request first check if that image is already generated and in the case it is, serve the blob directly (not 100% if this use case can be supported, but I guess it is).

   Anyway, more investigation on how to implement the service should be taken, so please do not take my words here as the right way to do it as I didn’t spent time on it when I created this issue.

GSoC 2024

This issue got accepted as part of the GSoC 2024. @helios2003 is assigned as mentee.

We are using the following read-only Project board to track the current status of it's work: https://github.com/orgs/asyncapi/projects/49/views/1