This action exposes the AsyncAPI CLI. It allows you to generate documentation, validate AsyncAPI documents, convert between different AsyncAPI versions and much more. The source code of the action can be found here
Inputs
cli_version
Version of the AsyncAPI CLI you wish to use. You can find all available versions here. Recommended leave it out of the inputs and use the default value.
Default points to thelatest version.
[!TIP] We recommend to default to
latestversion. This way there is no overhead with the script updating the CLI version. As it takes a lot of time to update the CLI version, we recommend to update it only when you need to use another one for compatibility reasons.
command
Command that you wish to run. You can find all available commands Available commands are:
generate- generates documentation from AsyncAPI documentvalidate- validates AsyncAPI documentoptimize- optimizes AsyncAPI documentconvert- converts AsyncAPI document to another versioncustom- allows you to run any command that is available in the AsyncAPI CLI. You can find all available commands here.
Default points to generate command.
[!IMPORTANT] In case you want to use
customcommand, you need to pass an array of commands to thecustom_commandinput. Although passing command is not required, it is recommended to pass it to avoid any issues later on. For example, if you want to runasyncapi bundle ./asyncapi.yaml --output final-asyncapi.yamlyou need to pass"bundle ./asyncapi.yaml --output final-asyncapi.yaml" to thecustom_command` input.
custom_command
In case you want to use custom command you need to pass the command that you want to run in this input. You can find all available commands here.
Default points to '' (empty string).
Sample usage:
1- name: Generating HTML from my AsyncAPI document
2 uses: asyncapi/cli@v2.16.0# You can use any version you want
3 with:
4 custom_command: bundle ./asyncapi.yaml --output final-asyncapi.yaml[!CAUTION] You have to pass the whole command as a string including the parameters and the command itself. It will run like this:
asyncapi <custom_command>
filepath
Path to the AsyncAPI document that you want to process.
Default expects the AsyncAPI document to be in the root of the repository and named asyncapi.yaml.
template
Template for the generator. Official templates are listed here https://github.com/asyncapi/generator#list-of-official-generator-templates. You can pass template as npm package, url to git repository, link to tar file or local template.
Default points to @asyncapi/markdown-template@0.10.0 template.
[!TIP] We recommend to always specify the version of the template to not encounter any issues with the action in case of release of the template that is not compatible with given version of the generator.
language
Specifies the language to be used for the generated models. The value must be a valid language name supported by modelina.
Default is not set.
[!WARNING] Either
languageortemplatemust be set else an error will be thrown. The action will return an error if the language is not supported by modelina.
output
Path to the output directory. Can be used for generate and convert commands.
Default points to output directory in the root of the repository.
parameters
The command that you use might support and even require specific parameters to be passed to the CLI for the generation. You can find all available parameters here.
Default points to '' (empty string).
[!NOTE] For template parameters, you need to pass them as
-p <template_parameters>as can be seen in CLI documentation.
Example usage
[!WARNING] Using
docker://asyncapi/github-action-for-cliwill not work as expected. This is because the GitHub Actions runner does not pass params to the docker image correctly. This is why we recommend to useasyncapi/cliinstead. However, you don't need to worry as it won't build the image every time. It will pull it from Docker Hub as it is already built there.
Basic
In case all defaults are fine for you, just add such step:
1- name: Generating Markdown from my AsyncAPI document
2 uses: asyncapi/cli@v2.16.0 # You can use any version you wantUsing all possible inputs
In case you do not want to use defaults, you for example want to use different template:
1- name: Generating HTML from my AsyncAPI document
2 uses: asyncapi/cli@v2.16.0 # You can use any version you want
3 with:
4 command: generate
5 filepath: ./docs/api/asyncapi.yaml
6 template: "@asyncapi/html-template@0.9.0" #In case of template from npm. Or can use a link.
7 output: ./generated-html
8 parameters: "-p baseHref=/test-experiment/ sidebarOrganization=byTags"[!IMPORTANT] Note the usage of
-pinparametersinput. This is required for template parameters, unlike previous versions of this action as the action includes other commands than justgenerate.
Example workflow with publishing generated HTML to GitHub Pages
In case you want to validate your asyncapi file first, and also send generated HTML to GitHub Pages this is how full workflow could look like:
1name: AsyncAPI documents processing
2
3on:
4 push:
5 branches: [ master ]
6
7jobs:
8 generate:
9 runs-on: ubuntu-latest
10 steps:
11 #"standard step" where repo needs to be checked-out first
12 - name: Checkout repo
13 uses: actions/checkout@v2
14
15 #In case you do not want to use defaults, you for example want to use different template
16 - name: Generating HTML from my AsyncAPI document
17 uses: asyncapi/cli@v2.16.0 # You can use any version you want
18 with:
19 template: '@asyncapi/html-template@0.9.0' #In case of template from npm, because of @ it must be in quotes
20 filepath: docs/api/my-asyncapi.yml
21 parameters: -p baseHref=/test-experiment/ sidebarOrganization=byTags #space separated list of key/values
22 output: generated-html
23
24 #Using another action that takes generated HTML and pushes it to GH Pages
25 - name: Deploy GH page
26 uses: JamesIves/github-pages-deploy-action@3.4.2
27 with:
28 ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
29 BRANCH: gh-pages
30 FOLDER: generated-htmlExample workflow for generating models
In case you want to use models generated from your AsyncAPI document, you can use this action to generate them and then use them in your workflow. This is how full workflow could look like:
1
2name: AsyncAPI documents processing
3
4on:
5 push:
6 branches: [ master ]
7
8jobs:
9 generate-models:
10 runs-on: ubuntu-latest
11 steps:
12 #"standard step" where repo needs to be checked-out first
13 - name: Checkout repo
14 uses: actions/checkout@v2
15
16 - name: Generating models from my AsyncAPI document
17 uses: asyncapi/cli@v2.16.0 # You can use any version you want
18 with:
19 command: generate
20 filepath: docs/api/my-asyncapi.yml
21 language: typescript
22 output: generated-modelsExample workflow for validating AsyncAPI document changes
In case you want to validate your AsyncAPI document changes, you can use this action to validate them and then use them in your workflow. This is how full workflow could look like:
1name: Validate AsyncAPI document
2
3on:
4 pull_request:
5 branches: [ master ]
6
7jobs:
8 validate:
9 runs-on: ubuntu-latest
10 steps:
11 #"standard step" where repo needs to be checked-out first
12 - name: Checkout repo
13 uses: actions/checkout@v2
14
15 - name: Validating AsyncAPI document
16 uses: asyncapi/cli@v2.16.0 # You can use any version you want
17 with:
18 command: validate
19 filepath: docs/api/my-asyncapi.ymlLocal dry run
Use following commands to run and test github action locally:
- Build docker image of github action for cli
npm run action:docker:build- Execute docker image with proper arguments
docker run -e GITHUB_WORKSPACE="" --workdir /action -v "/home/{user}/path/to/repo":"/action" asyncapi/github-action-for-cli "" "generate" "github-action/test/asyncapi.yml" "@asyncapi/markdown-template@0.10.0" "" "output" "" ""Make sure to change the path of the repo and user in the command.
Troubleshooting
You can enable more log information in GitHub Action by adding ACTIONS_STEP_DEBUG secret to repository where you want to use this action. Set the value of this secret to true and you''ll notice more debug logs from this action.
