DocsUI: UX/UI updates

[mcturco]

Description
Just wanted to open this issue as I have been working on some UX/UI updates to the documentation components and wanted to create a "home" to post some iterations and get some feedback from the community.

I have an idea to rename this repo: DocsUI asyncapi/docs-ui for when the first iteration of these component updates are complete. That way we can package these components and allow for others to use each one in their own projects where they are outputting documentation with their asyncapi files. Would like to know everyone's thoughts on that!

There are a quite a few different improvements we need to make, so wanted to break them down into separate tasks to make it easier to keep track of. I could also break these out into separate issues for each one if that is easier?

Scope

• Sidebar Navigation
• Info Object output
• Servers Object output
• Operations Object output
• DocsUI: Messages Object output #618
• Examples output
• Schema output

Schema output: added this for now, but I think we should discuss if this is needed for docs output.

We can definitely add more to this list if needed, but I think these components are the foundation of the DocsUI so we can make a lot of great updates just by re-designing these.

[magicmatatjahu]

@mcturco I love it ❤️

I have an idea to rename this repo: DocsUI asyncapi/docs-ui for when the first iteration of these component updates are complete. That way we can package these components and allow for others to use each one in their own projects where they are outputting documentation with their asyncapi files. Would like to know everyone's thoughts on that!

We have similar issue for that I added suggestion to have only @asyncapi/ui like here #263 (comment) By this we can have several kits in single project :) About packaging: if we will write everything by ESM (EcmaScript Modules) users will have option to use only needed components and rest will be shaking from final app. In our cases with kits I'm not a fan of multiple repositories and packages, one should be enough :)

Schema output (added this for now, but I think we should discuss if this is needed for docs output)

It's probably one of most important and probably hardest to implement component because we render channel parameters, server variables, message payload/headers by this component, so in the Messages Object output we should use that Schema component.

[mcturco]

We have similar issue for that I added suggestion to have only @asyncapi/ui like here #263 (comment) By this we can have several kits in single project :)

This sounds great to me! Whatever you think makes sense from a technical standpoint 😄

It's probably one of most important and probably hardest to implement component because we render channel parameters, server variables, message payload/headers by this component, so in the Messages Object output we should use that Schema component.

I guess my question relates more to the idea to only remove the Schemas section in the documentation output because it is redundant. If we just show the schema at each message level, it might be a better experience rather than telling the user to go somewhere else to view the message schema. Not sure if that makes sense, but I know @fmvilas mentioned this to me once before as well so maybe he can shed more light on the topic 😄

[fmvilas]

Yeah, the schemas section is a tool for the AsyncAPI author, I mean, for the author of the document. It's not really important for the documentation consumer. Messages are, and messages contain the schemas already. For those who are authoring the AsyncAPI document, they have the Studio sidebar where all the schemas are listed.

[magicmatatjahu]

But schemas section can always be removed from the generated UI via config.

If we just show the schema at each message level, it might be a better experience rather than telling the user to go somewhere else to view the message schema.

I see your point of view, but we render schema for payload etc in place where we should, we don't make a link to the schema section. As Fran said, it's only for developers.

I hope it's clear now :)

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[fmvilas]

Still way relevant 😄

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[asmitbm]

Hey @mcturco,

I'm interested to work on this issue!