[📑 Docs]: example/demo on html-template

[tkp-richard]

What Dev Docs changes are you proposing?

hi, i'm a primarily backend dev who's currently using openapi to document my apis, i'm currently interested in asyncapi since i need to document some SSE APIs and the folks as openapi don't seem to be interested in supporting it.

i don't do any frontend development at all on my company laptop so i don't even have npm installed on it (nor am i familiar with most frontend tools). i'll probably install them after this but i think it would be pretty helpful for others who are looking to convert if asyncapi had a demo page.

also, lots of the mainstream openapi renderers can simply take a link to the yaml file in a plain html file (redoc, swagger, etc) is this something that asyncapi is planning to support in the future?

Code of Conduct

• I agree to follow this project's Code of Conduct

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[derberg]

@tkp-richard it makes a lot of sense what you write.

In case of this repo we could do 2 things:

• have automation in place that uses https://github.com/asyncapi/github-action-for-generator and whenever we update the template, a preview example us pushed to GH Pages and visible for anyone, like I played with it in https://github.com/derberg/test-experiment/blob/master/.github/workflows/main.yml and https://derberg.github.io/test-experiment/
• update readme with important links:
  • that https://studio.asyncapi.com/ is powered by the same component that this html-template so you can see how it looks like, and also there is a download template that uses this html-template
  • maybe link article like https://www.asyncapi.com/blog/event-driven-api-documentation-made-simple-clientside-rendering to show also alternatives

What do you think of it? and would you be open to help?

[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 ❤️

[serkmen]

Hello,
Thank you. This response helped me a lot for the same question.
I tried to create same playground to create my own demo shared by @derberg -> https://github.com/derberg/test-experiment/blob/master/.github/workflows/main.yml

However, my GitHub actions stuck with following error even I was trying with different generator versions.
Could you please share comments on that?
Thank you

[derberg]

@serkmen did you use the same workflow file that I shared? 1:1? or did some modifications?

[serkmen]

@derberg
Reported error can be re-producible when it is switched to the latest ones --> generator:2.1.26 and @asyncapi/html-template@2.0.0
`
name: AsyncAPI documents processing

on:
push:
branches:
- feature/aysncapi-integration
permissions: write-all
jobs:
generate:
runs-on: ubuntu-latest
steps:
#"standard step" where repo needs to be checked-out first
- name: Checkout repo
uses: actions/checkout@v2
#In case you do not want to use defaults, you for example want to use different template
- name: Generating HTML from my AsyncAPI document
uses: docker://asyncapi/github-action-for-generator:2.1.26
with:
template: '@asyncapi/html-template@2.0.0'
filepath: docs/api/asyncapi.yml
parameters: pdf=true baseHref=/test-experiment/ sidebarOrganization=byTags #space separated list of key/values
output: generated-html
- name: Checking if stuff are available outside container
run: echo "===" && ls && echo "===" && ls generated-html && echo "==="
#Using another action that takes generated HTML and pushes it to GH Pages
- name: Deploy GH page
uses: JamesIves/github-pages-deploy-action@3.4.2
with:
ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BRANCH: gh-pages
FOLDER: generated-html
`

Runner Error:

47s Run docker://asyncapi/github-action-for-generator:2.1.26 with: template: @asyncapi/html-template@2.0.0 filepath: docs/api/asyncapi.yml parameters: pdf=true baseHref=/test-experiment/ sidebarOrganization=byTags output: generated-html /usr/bin/docker run --name asyncapigithubactionforgenerator2126_42a3b7 --label c59b73 --workdir /github/workspace --rm -e "INPUT_TEMPLATE" -e "INPUT_FILEPATH" -e "INPUT_PARAMETERS" -e "INPUT_OUTPUT" -e "HOME" -e "GITHUB_JOB" -e "GITHUB_REF" -e "GITHUB_SHA" -e "GITHUB_REPOSITORY" -e "GITHUB_REPOSITORY_OWNER" -e "GITHUB_REPOSITORY_OWNER_ID" -e "GITHUB_RUN_ID" -e "GITHUB_RUN_NUMBER" -e "GITHUB_RETENTION_DAYS" -e "GITHUB_RUN_ATTEMPT" -e "GITHUB_REPOSITORY_ID" -e "GITHUB_ACTOR_ID" -e "GITHUB_ACTOR" -e "GITHUB_TRIGGERING_ACTOR" -e "GITHUB_WORKFLOW" -e "GITHUB_HEAD_REF" -e "GITHUB_BASE_REF" -e "GITHUB_EVENT_NAME" -e "GITHUB_SERVER_URL" -e "GITHUB_API_URL" -e "GITHUB_GRAPHQL_URL" -e "GITHUB_REF_NAME" -e "GITHUB_REF_PROTECTED" -e "GITHUB_REF_TYPE" -e "GITHUB_WORKFLOW_REF" -e "GITHU47s Run docker://asyncapi/github-action-for-generator:2.1.26 with: template: @asyncapi/html-template@2.0.0 filepath: docs/api/asyncapi.yml parameters: pdf=true baseHref=/test-experiment/ sidebarOrganization=byTags output: generated-html /usr/bin/docker run --name asyncapigithubactionforgenerator2126_42a3b7 --label c59b73 --workdir /github/workspace --rm -e "INPUT_TEMPLATE" -e "INPUT_FILEPATH" -e "INPUT_PARAMETERS" -e "INPUT_OUTPUT" -e "HOME" -e "GITHUB_JOB" -e "GITHUB_REF" -e "GITHUB_SHA" -e "GITHUB_REPOSITORY" -e "GITHUB_REPOSITORY_OWNER" -e "GITHUB_REPOSITORY_OWNER_ID" -e "GITHUB_RUN_ID" -e "GITHUB_RUN_NUMBER" -e "GITHUB_RETENTION_DAYS" -e "GITHUB_RUN_ATTEMPT" -e "GITHUB_REPOSITORY_ID" -e "GITHUB_ACTOR_ID" -e "GITHUB_ACTOR" -e "GITHUB_TRIGGERING_ACTOR" -e "GITHUB_WORKFLOW" -e "GITHUB_HEAD_REF" -e "GITHUB_BASE_REF" -e "GITHUB_EVENT_NAME" -e "GITHUB_SERVER_URL" -e "GITHUB_API_URL" -e "GITHUB_GRAPHQL_URL" -e "GITHUB_REF_NAME" -e "GITHUB_REF_PROTECTED" -e "GITHUB_REF_TYPE" -e "GITHUB_WORKFLOW_REF" -e "GITHUB_WB_WORKFLOW_SHA" -e "GITHUB_WORKSPACE" -e "GITHUB_ACTION" -e "GITHUB_EVENT_PATH" -e "GITHUB_ACTION_REPOSITORY" -e "GITHUB_ACTION_REF" -e "GITHUB_PATH" -e "GITHUB_ENV" -e "GITHUB_STEP_SUMMARY" -e "GITHUB_STATE" -e "GITHUB_OUTPUT" -e "RUNNER_OS" -e "RUNNER_ARCH" -e "RUNNER_NAME" -e "RUNNER_ENVIRONMENT" -e "RUNNER_TOOL_CACHE" -e "RUNNER_TEMP" -e "RUNNER_WORKSPACE" -e "ACTIONS_RUNTIME_URL" -e "ACTIONS_RUNTIME_TOKEN" -e "ACTIONS_CACHE_URL" -e "ACTIONS_ID_TOKEN_REQUEST_URL" -e "ACTIONS_ID_TOKEN_REQUEST_TOKEN" -e "ACTIONS_RESULTS_URL" -e GITHUB_ACTIONS=true -e CI=true -v "/var/run/docker.sock":"/var/run/docker.sock" -v "/home/runner/work/_temp/_github_home":"/github/home" -v "/home/runner/work/_temp/_github_workflow":"/github/workflow" -v "/home/runner/work/_temp/_runner_file_commands":"/github/file_commands" -v "/home/runner/work/swaggerui-in-git/swaggerui-in-git":"/github/workspace" asyncapi/github-action-for-generator:2.1.26 [BABEL] Note: The code generator has deoptimised the styling of /node_modules/@asyncapi/generator/node_modules/@asyncapi/html-template/template/js/asyncapi-ui.min.js as it exceeds the max of 500KB. Error: Found non-callable @@iterator

HTML generation works if I switch back to html-template@1.0.0 with same workflow. This time GH Pages could not load the css and js folder for the given structure and displays only the parsed plain text :(

[derberg]

@serkmen should be solved with #490 and latest html-template 2.1

[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 ❤️