asyncapi/html-template

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

tkp-richard opened this issue · 8 comments

tkp-richard commented

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 commented

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 commented

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

In case of this repo we could do 2 things:

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

  • 👍1
github-actions commented

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 commented

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

image

derberg commented

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

serkmen commented

@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 :(

image