feat: show event examples

[thim81]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

Currently the application can display an Event Schema (JSON schema representation) and Code Examples.

It would also be nice to show an example of the "event" itself, especially if the event is in a JSON or non-binary format.
Where you see the "Event Schema" and the "Event Example" next to each other.

Example: https://redocly.github.io/redoc/#tag/pet

Motivation

A common use-case for event documentation, is to have an actual example that makes the documentation and event very visual. An event schema describes the properties and the details on these properties. An event example shows the event content/data.

[dytyniuk]

Hi @thim81

Can the Code Examples feature help with your case?

[boyney123]

Hey @thim81 ,

Thanks for the idea, just looking at everything now, I was certain this was supported already but I can't find anything 😅, yeah great idea. I guess we could add /event-examples directory or something inside the events and let peolpe just add any filetype they want and have the UI render it?

Following from @dytyniuk yeah I guess Code Examples could work there too, but I guess if we had an explicit place we could store this stuff might be better?

Any ideas on where we could store examples of the events? My thoughts is add a new directory and if events are in there maybe the UI can render them, or user opt-in into new component

[thim81]

hi @boyney123

Adding /event-examples directory would be a very logical solution.

The tricky part will be the rendering part and I guess mostly the UI aspect, like where to put the example in the event details screen.

Where to put this?

[dytyniuk]

hi @boyney123

I thought about your suggestion to add the event-examples directory a bit. And here is what I have come through:

1. At first I had a thought, it would be enough to have a single example of the event. Just like with its' schema -- if you have some other example, that could be lookling as a new version of the event. So, an example based on a single file looked legit.
2. Although, I have realised, that the event can contain optional properties, and one may need to show more that one example.
3. You have already implemeted the examples directory to keep code samples. How about adding an extra directory there? Something like this:

└─ events
   ├─ index.md
   ├─ schema.json
   └─ examples
      ├─ code-sample.js
      └─ event
         ├─ example-a.json
         └─ example-b.json

@thim81 does look like something helping with your issue?

[boyney123]

hi @boyney123

Adding /event-examples directory would be a very logical solution.

The tricky part will be the rendering part and I guess mostly the UI aspect, like where to put the example in the event details screen.

Where to put this?

Maybe an MDX Component that people can choose where to put it.

I might also explore some kind of component that allows people to put things side by side, in your example it could be

<Splitter>
    <SchemaViewer/>
    <EventExample example="example1" />
</Splitter>

This could render the things side by side and allow you to choose which event example to render

[thim81]

@boyney123 The <splitter> would be really interesting, since you typically want to have the example and schema properties in 1 view to be able to understand what is shown.

[boyney123]

hi @boyney123

I thought about your suggestion to add the event-examples directory a bit. And here is what I have come through:

1. At first I had a thought, it would be enough to have a single example of the event. Just like with its' schema -- if you have some other example, that could be lookling as a new version of the event. So, an example based on a single file looked legit.
2. Although, I have realised, that the event can contain optional properties, and one may need to show more that one example.
3. You have already implemeted the examples directory to keep code samples. How about adding an extra directory there? Something like this:

└─ events
   ├─ index.md
   ├─ schema.json
   └─ examples
      ├─ code-sample.js
      └─ event
         ├─ example-a.json
         └─ example-b.json

@thim81 does look like something helping with your issue?

Yeah I like this solution, keeping the examples code in the one place, I will implement it and see how it feels and make sure it does not impact the other components. Thanks!

[thim81]

Just thinking of this some more, once this in is place, it would be interesting to extend the asyncapi generator to dump the "examples" in the appropriate files.