Another documentation generator

[jfveronelli]

I'd like to submit for your consideration as a "documentation generator" a wrapper around the AsyncAPI-React component. It let's a microservice expose it's AsyncAPI spec pretty easily by using a static HTML page with a couple of tags.

The project is at https://github.com/jfveronelli/instant-asyncapi-doc

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue.

Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[derberg]

@jfveronelli that looks awesome man. Zero react knowledge needed, just grab JS from CDN. Thanks a lot for sharing.

I shamefully have to admit I've not used Parcel before and do not have much knowledge about it. JS world has so many tools 😅

We just recently talked with @fmvilas about the future of UI, that we now have 2 UI projects that require maintenance, the react component for SPA apps, and the html-template for SSR apps + static generation with generator CLI. We thought that probably better to focus on react component and just make sure it can be used not only for SPA but also have a solution to prerender it for static sites purposes (just like you have prerendering supported in Gatsby for example).

What is your long term plan for instant-asyncapi-doc?
So as you can see many ideas in our heads

[jfveronelli]

Hi Lukasz. I've very basic knowledge regarding nodejs tools and modern JS frameworks. So I picked Parcel because it looked simple enough and covering the required use case.

I took the idea of grabbing some JS and using it to present an API document from ReDoc. We use it in some microservices to present their OpenAPI specs. They're implemented in Lagom (scala), which lacks much of OpenAPI or AsyncAPI support. So ReDoc worked like a charm to do something resembling what Swagger UI does for Spring Boot.

Regarding AsyncAPI we wanted to do something similar, and we saw that the two options were using AsyncAPI Generator to make the static HTMLs pages, or make some React application to be able to use the AsyncAPI React component. Both solutions would involve incorporating nodejs to our toolchain, and making it more complex than needed.

So I created this wrapper to fill the gap. We're using it in production for our internal services. So, long term plan is keeping it working, backward-compatible, and up-to-date with AsyncAPI-React. Hopefully I'll have some time to add tests and CI/CD.

Unfortunately I don't have enough background or modern JS tools knowledge to help on the dilemma of supporting 2 different UI projects or replacing one by enhancing the other.

[derberg]

@jfveronelli what if....what if we join forces? I say that if you see a need for such a wrapper and you not only have a use case for it, but also know others (like ReDoc) do it....why not joining forces. Do you want to maintain it separately or rather join asyncapi-react, have some discussion, and integrate it with our GitHub Action pipeline, so we always publish it up to date with the latest version? of course no pressure, and this is completely fine if you want to maintain it separately

[wills-feng]

Thank you @derberg for bringing me here. This is indeed what I am looking for, a way to dynamically render Asyncapi spec to
HTML, like Redoc.js. Thank you @jfveronelli for the fantastic work.

[ashuks]

Hi @derberg , thanks for pointing this solution to me and thanks @jfveronelli for this. It meets my requirement. @derberg ,I have a question here, the document rendered via React app is different from the rendered document via SSR app for the same Async API definition. Any known reason for this?

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[derberg]

@jfveronelli @ashuks @xiaohuangji I have awesome news for you

Thanks to great work from @hesyar and @gexclaude that worked on adding a Web Component to the React Component, thanks to @magicmatatjahu who prepared a release pipeline, and thanks to @aeworxet who made some minor DX improvements with the latest 0.19.0 release below you have an example of how easy you can render your specification into beautiful documentation. This is not officially supported and every new improvement to the component will also be included there as well

You just create index.html file like below and it works like a charm

<script src="https://unpkg.com/@webcomponents/webcomponentsjs@2.5.0/webcomponents-bundle.js"></script>
<script src="https://unpkg.com/@asyncapi/web-component@0.19.0/lib/asyncapi-web-component.js" defer></script>

<asyncapi-component
  schemaUrl="https://raw.githubusercontent.com/asyncapi/asyncapi/master/examples/2.0.0/streetlights.yml"
  cssImportPath="https://unpkg.com/@asyncapi/react-component@0.19.0/lib/styles/fiori.css">
</asyncapi-component>

Enjoy!