Skip to content

Commit b28aadc

Browse files
Lemeri123Lemeri123
authored
Merge branch 'master' into work
2 parents 45d22b2 + b2711af commit b28aadc

File tree

15 files changed

+294
-307
lines changed

15 files changed

+294
-307
lines changed

‎.changeset/five-moles-care.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22
"@asyncapi/cli": patch
33
---
44

5-
Added UI/UX improvements to start command
5+
implemented new UI/UX improvements in config command

‎README.md

+4
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ CLI to work with your AsyncAPI files. Currently under development, we are workin
1212

1313
- [Installation](#installation)
1414
- [Usage](#usage)
15+
- [Github Action](#github-action)
1516
- [Contributing](#contributing)
1617
* [Set up development environment](#set-up-development-environment)
1718
* [Command Structure and Patterns](#command-structure-and-patterns)
@@ -25,6 +26,9 @@ Learn how to install the AsyncAPI CLI by following the instructions in the [inst
2526
## Usage
2627
The [usage guide](/docs/usage.md) provides information about different ways to use the CLI.
2728

29+
## Github Action
30+
31+
The AsyncAPI CLI can be used as a GitHub Action. You can find more information in the [GitHub Action guide](https://www.asyncapi.com/docs/tools/cli/github-action).
2832

2933
## Contributing
3034

‎docs/github-action.md

+239
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
---
2+
title: GitHub Action for CLI
3+
weight: 50
4+
---
5+
6+
This action exposes the [AsyncAPI CLI](https://github.com/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](https://github.com/asyncapi/cli/tree/master/github-action)
7+
8+
## Inputs
9+
10+
### `cli_version`
11+
12+
Version of the AsyncAPI CLI you wish to use. You can find all available versions [here](https://github.com/asyncapi/cli/releases). Recommended leave it out of the inputs and use the default value.
13+
14+
**Default** points to the`latest` version.
15+
16+
> [!TIP]
17+
> We recommend to default to `latest` version. 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.
18+
19+
### `command`
20+
21+
Command that you wish to run. You can find all available commands Available commands are:
22+
- `generate` - generates documentation from AsyncAPI document
23+
- `validate` - validates AsyncAPI document
24+
- `optimize` - optimizes AsyncAPI document
25+
- `convert` - converts AsyncAPI document to another version
26+
- `custom` - allows you to run any command that is available in the AsyncAPI CLI. You can find all available commands [here](https://www.asyncapi.com/docs/tools/cli/usage).
27+
28+
**Default** points to `generate` command.
29+
30+
> [!IMPORTANT]
31+
> In case you want to use `custom` command, you need to pass an array of commands to the [`custom_command`](#custom_command) input. Although passing command is not required, it is recommended to pass it to avoid any issues later on.
32+
> For example, if you want to run `asyncapi bundle ./asyncapi.yaml --output final-asyncapi.yaml` you need to pass `"bundle ./asyncapi.yaml --output final-asyncapi.yaml" to the `custom_command` input.
33+
34+
### `custom_command`
35+
36+
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](https://www.asyncapi.com/docs/tools/cli/usage).
37+
38+
**Default** points to '' (empty string).
39+
40+
Sample usage:
41+
42+
```yaml
43+
- name: Generating HTML from my AsyncAPI document
44+
uses: asyncapi/[email protected]# You can use any version you want
45+
with:
46+
custom_command: bundle ./asyncapi.yaml --output final-asyncapi.yaml
47+
```
48+
49+
> [!CAUTION]
50+
> You have to pass the whole command as a string including the parameters and the command itself.
51+
> It will run like this: `asyncapi <custom_command>`
52+
53+
54+
### `filepath`
55+
56+
Path to the AsyncAPI document that you want to process.
57+
58+
**Default** expects the AsyncAPI document to be in the root of the repository and named `asyncapi.yaml`.
59+
60+
### `template`
61+
62+
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.
63+
64+
**Default** points to `@asyncapi/[email protected]` template.
65+
66+
> [!TIP]
67+
> 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.
68+
69+
### `language`
70+
71+
Specifies the language to be used for the generated models. The value must be a valid language name supported by [modelina](https://github.com/asyncapi/modelina).
72+
73+
**Default** is not set.
74+
75+
> [!WARNING]
76+
> Either `language` or `template` must be set else an error will be thrown.
77+
> The action will return an error if the language is not supported by [modelina](https://github.com/asyncapi/modelina).
78+
79+
### `output`
80+
81+
Path to the output directory. Can be used for `generate` and `convert` commands.
82+
83+
**Default** points to `output` directory in the root of the repository.
84+
85+
### `parameters`
86+
87+
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](https://www.asyncapi.com/docs/tools/cli/usage).
88+
89+
**Default** points to '' (empty string).
90+
91+
> [!NOTE]
92+
> For template parameters, you need to pass them as `-p <template_parameters>` as can be seen in CLI documentation.
93+
94+
95+
## Example usage
96+
97+
> [!WARNING]
98+
> Using `docker://asyncapi/github-action-for-cli` will 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 use `asyncapi/cli` instead.
99+
> 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.
100+
101+
### Basic
102+
103+
In case all defaults are fine for you, just add such step:
104+
105+
```yaml
106+
- name: Generating Markdown from my AsyncAPI document
107+
uses: asyncapi/[email protected] # You can use any version you want
108+
```
109+
110+
### Using all possible inputs
111+
112+
In case you do not want to use defaults, you for example want to use different template:
113+
114+
```yaml
115+
- name: Generating HTML from my AsyncAPI document
116+
uses: asyncapi/[email protected] # You can use any version you want
117+
with:
118+
command: generate
119+
filepath: ./docs/api/asyncapi.yaml
120+
template: "@asyncapi/[email protected]" #In case of template from npm. Or can use a link.
121+
output: ./generated-html
122+
parameters: "-p baseHref=/test-experiment/ sidebarOrganization=byTags"
123+
```
124+
> [!IMPORTANT]
125+
> Note the usage of `-p` in `parameters` input. This is required for template parameters, unlike previous versions of this action as the action includes other commands than just `generate`.
126+
127+
### Example workflow with publishing generated HTML to GitHub Pages
128+
129+
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:
130+
131+
```yaml
132+
name: AsyncAPI documents processing
133+
134+
on:
135+
push:
136+
branches: [ master ]
137+
138+
jobs:
139+
generate:
140+
runs-on: ubuntu-latest
141+
steps:
142+
#"standard step" where repo needs to be checked-out first
143+
- name: Checkout repo
144+
uses: actions/checkout@v2
145+
146+
#In case you do not want to use defaults, you for example want to use different template
147+
- name: Generating HTML from my AsyncAPI document
148+
uses: asyncapi/[email protected] # You can use any version you want
149+
with:
150+
template: '@asyncapi/[email protected]' #In case of template from npm, because of @ it must be in quotes
151+
filepath: docs/api/my-asyncapi.yml
152+
parameters: -p baseHref=/test-experiment/ sidebarOrganization=byTags #space separated list of key/values
153+
output: generated-html
154+
155+
#Using another action that takes generated HTML and pushes it to GH Pages
156+
- name: Deploy GH page
157+
uses: JamesIves/[email protected]
158+
with:
159+
ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
160+
BRANCH: gh-pages
161+
FOLDER: generated-html
162+
```
163+
164+
### Example workflow for generating models
165+
166+
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:
167+
168+
```yaml
169+
170+
name: AsyncAPI documents processing
171+
172+
on:
173+
push:
174+
branches: [ master ]
175+
176+
jobs:
177+
generate-models:
178+
runs-on: ubuntu-latest
179+
steps:
180+
#"standard step" where repo needs to be checked-out first
181+
- name: Checkout repo
182+
uses: actions/checkout@v2
183+
184+
- name: Generating models from my AsyncAPI document
185+
uses: asyncapi/[email protected] # You can use any version you want
186+
with:
187+
command: generate
188+
filepath: docs/api/my-asyncapi.yml
189+
language: typescript
190+
output: generated-models
191+
```
192+
193+
### Example workflow for validating AsyncAPI document changes
194+
195+
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:
196+
197+
```yaml
198+
name: Validate AsyncAPI document
199+
200+
on:
201+
pull_request:
202+
branches: [ master ]
203+
204+
jobs:
205+
validate:
206+
runs-on: ubuntu-latest
207+
steps:
208+
#"standard step" where repo needs to be checked-out first
209+
- name: Checkout repo
210+
uses: actions/checkout@v2
211+
212+
- name: Validating AsyncAPI document
213+
uses: asyncapi/[email protected] # You can use any version you want
214+
with:
215+
command: validate
216+
filepath: docs/api/my-asyncapi.yml
217+
```
218+
219+
## Local dry run
220+
221+
Use following commands to run and test github action locally:
222+
223+
1. Build docker image of github action for cli
224+
225+
```bash
226+
npm run action:docker:build
227+
```
228+
229+
2. Execute docker image with proper arguments
230+
231+
```bash
232+
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/[email protected]" "" "output" "" ""
233+
```
234+
235+
Make sure to change the path of the repo and user in the command.
236+
237+
## Troubleshooting
238+
239+
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.

0 commit comments

Comments
 (0)