diff --git a/.github/workflows/release-docker.yml b/.github/workflows/release-docker.yml new file mode 100644 index 00000000000..24c62b9c7c4 --- /dev/null +++ b/.github/workflows/release-docker.yml @@ -0,0 +1,37 @@ +name: Release Docker Image +on: + release: + types: + - published +jobs: + + publish-docker: + name: Generating Docker + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v3 + - name: Get version without v character + id: version + run: | + VERSION=${{github.event.release.tag_name}} + VERSION_WITHOUT_V=${VERSION:1} + echo "value=${VERSION_WITHOUT_V}" >> $GITHUB_OUTPUT + + - name: Release to Docker + run: | + echo ${{secrets.DOCKER_PASSWORD}} | docker login -u ${{secrets.DOCKER_USERNAME}} --password-stdin + npm run docker:build + docker tag asyncapi/cli:latest asyncapi/cli:${{ steps.version.outputs.value }} + docker push asyncapi/cli:${{ steps.version.outputs.value }} + docker push asyncapi/cli:latest + + - name : Sync README.md and Description to Docker Hub + uses: actions/checkout@master + + - uses: meeDamian/sync-readme@v1.0.6 + with: + user: ${{secrets.DOCKER_USERNAME}} + pass: ${{ secrets.DOCKER_PASSWORD }} + slug: asyncapi/cli + description: CLI to work with your AsyncAPI files diff --git a/.github/workflows/update-docs-on-docs-commits.yml b/.github/workflows/update-docs-on-docs-commits.yml new file mode 100644 index 00000000000..9d4405e3234 --- /dev/null +++ b/.github/workflows/update-docs-on-docs-commits.yml @@ -0,0 +1,37 @@ +name: 'Update generated parts of documentation on docs: commits' + +on: + push: + branches: + - master + +jobs: + docs-gen: + name: 'Generate docs and create PR' + # PR should be created within this GH action only if it is a docs: commit + # Otherwise it will conflict with release workflow + if: startsWith(github.event.commits[0].message, 'docs:') + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v3 + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: 18 + - name: Install dependencies + run: npm ci + - name: Regenerate docs + run: npm run generate:assets --if-present + - name: Create Pull Request with updated docs + if: startsWith(github.event.commits[0].message, 'docs:') + uses: peter-evans/create-pull-request@v3 + with: + token: ${{ secrets.GH_TOKEN }} + commit-message: 'chore: update generated docs' + committer: asyncapi-bot + author: asyncapi-bot + title: 'chore: update generated docs' + body: 'Update of docs that are generated and were forgotten on PR level.' + branch: gen-docs-update + \ No newline at end of file diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000000..1e1ad3adc07 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,24 @@ +FROM node:16-alpine + +# Create a non-root user +RUN addgroup -S myuser && adduser -S myuser -G myuser + +WORKDIR /app + +# Since 0.14.0 release of html-template chromium is needed for pdf generation +ENV PUPPETEER_EXECUTABLE_PATH /usr/bin/chromium-browser +ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD true +# Since 0.30.0 release Git is supported and required as a dependency +# Since 0.14.0 release of html-template chromium is needed for pdf generation. +# More custom packages for specific template should not be added to this dockerfile. Instead, we should come up with some extensibility solution. +RUN apk --update add git chromium && \ + rm -rf /var/lib/apt/lists/* && \ + rm /var/cache/apk/* + +# Installing latest released npm package +RUN npm install --ignore-scripts -g @asyncapi/cli + +# Switch to the non-root user +USER myuser + +ENTRYPOINT [ "asyncapi" ] \ No newline at end of file diff --git a/create-glee-app/templates/default/package-lock.json b/create-glee-app/templates/default/package-lock.json index 3961a1cd14d..5e7b2fb7341 100644 --- a/create-glee-app/templates/default/package-lock.json +++ b/create-glee-app/templates/default/package-lock.json @@ -9,7 +9,7 @@ "version": "0.1.0", "license": "Apache-2.0", "dependencies": { - "@asyncapi/glee": "^0.21.0" + "@asyncapi/glee": "^0.21.4" }, "engines": { "node": ">=14.15.1" @@ -211,9 +211,9 @@ } }, "node_modules/@asyncapi/glee": { - "version": "0.21.0", - "resolved": "https://registry.npmjs.org/@asyncapi/glee/-/glee-0.21.0.tgz", - "integrity": "sha512-djuAmg+PeSslS7XSo/pgAy8RIvUG9CqPQsefMvoVx0ct9O33/B34jy9aGmeVxRnD/nZUb0SrgiAwBJ4xk1Y0/g==", + "version": "0.21.4", + "resolved": "https://registry.npmjs.org/@asyncapi/glee/-/glee-0.21.4.tgz", + "integrity": "sha512-ENtuax/mqZQuR56SCQA7NWl0b/iBn1xfqxILKyY796rK9Y25QOmWFFaFzyCPHEJGkbRpfkNrGcR4CyMd+rj6IA==", "dependencies": { "@asyncapi/generator": "^1.9.18", "@asyncapi/html-template": "^0.24.10", @@ -226,7 +226,6 @@ "better-ajv-errors": "^0.7.0", "bufferutil": "^4.0.3", "chalk": "^4.1.1", - "conventional-changelog-conventionalcommits": "^5.0.0", "cross-spawn": "^7.0.3", "debug": "^4.3.1", "dotenv": "^10.0.0", @@ -10803,9 +10802,9 @@ } }, "@asyncapi/glee": { - "version": "0.21.0", - "resolved": "https://registry.npmjs.org/@asyncapi/glee/-/glee-0.21.0.tgz", - "integrity": "sha512-djuAmg+PeSslS7XSo/pgAy8RIvUG9CqPQsefMvoVx0ct9O33/B34jy9aGmeVxRnD/nZUb0SrgiAwBJ4xk1Y0/g==", + "version": "0.21.4", + "resolved": "https://registry.npmjs.org/@asyncapi/glee/-/glee-0.21.4.tgz", + "integrity": "sha512-ENtuax/mqZQuR56SCQA7NWl0b/iBn1xfqxILKyY796rK9Y25QOmWFFaFzyCPHEJGkbRpfkNrGcR4CyMd+rj6IA==", "requires": { "@asyncapi/generator": "^1.9.18", "@asyncapi/html-template": "^0.24.10", @@ -10818,7 +10817,6 @@ "better-ajv-errors": "^0.7.0", "bufferutil": "^4.0.3", "chalk": "^4.1.1", - "conventional-changelog-conventionalcommits": "^5.0.0", "cross-spawn": "^7.0.3", "debug": "^4.3.1", "dotenv": "^10.0.0", diff --git a/create-glee-app/templates/default/package.json b/create-glee-app/templates/default/package.json index 74e8d7a4bd0..ac9bf56cd36 100644 --- a/create-glee-app/templates/default/package.json +++ b/create-glee-app/templates/default/package.json @@ -24,6 +24,6 @@ }, "homepage": "https://github.com/asyncapi/glee-hello-world#readme", "dependencies": { - "@asyncapi/glee": "^0.21.0" + "@asyncapi/glee": "^0.21.4" } } diff --git a/docs/installation.md b/docs/installation.md index 80d0b52d483..c3bdf6aba64 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -25,6 +25,30 @@ After installing Node.js and NPM, run the following command to install the Async ```sh npm install -g @asyncapi/cli ``` +## Docker + +Install [Docker](https://docs.docker.com/get-docker/) first, then use docker to build the image using the following command : +``` +docker build -t asyncapi/cli:latest . +``` +and run the image using the following command : + +```bash +docker run --rm -it \ +--user=root \ +-v [ASYNCAPI SPEC FILE LOCATION]:/app/asyncapi.yml \ +-v [GENERATED FILES LOCATION]:/app/output \ +asyncapi/cli [COMMAND HERE] + +# Example that you can run inside the cli directory after cloning this repository. First, you specify the mount in the location of your AsyncAPI specification file and then you mount it in the directory where the generation result should be saved. +docker run --rm -it \ + --user=root \ + -v ${PWD}/test/fixtures/asyncapi_v1.yml:/app/asyncapi.yml \ + -v ${PWD}/output:/app/output \ + asyncapi/cli generate fromTemplate -o /app/output /app/asyncapi.yml @asyncapi/html-template --force-write +``` +Note: Use ``` ` ``` instead of `\` for Windows. + ## Mac There are two ways to install the AsyncAPI CLI on your macOS: using the `brew` package manager or `pkg` files. diff --git a/docs/usage.md b/docs/usage.md index 2bc42daf1a8..08ee3bb9187 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -3,45 +3,556 @@ title: 'Usage' weight: 40 --- + + The AsyncAPI CLI makes it easier to work with AsyncAPI documents. -To get **help**, run this command in your terminal: -```sh -asyncapi --help +# Usage + + +```sh-session +$ npm install -g @asyncapi/cli +$ asyncapi COMMAND +running command... +$ asyncapi (--version) +@asyncapi/cli/0.48.5 linux-x64 node-v18.16.0 +$ asyncapi --help [COMMAND] +USAGE + $ asyncapi COMMAND +... +``` + + +# Commands + + +* [`asyncapi bundle`](#asyncapi-bundle) +* [`asyncapi config`](#asyncapi-config) +* [`asyncapi config context`](#asyncapi-config-context) +* [`asyncapi config context add CONTEXT-NAME SPEC-FILE-PATH`](#asyncapi-config-context-add-context-name-spec-file-path) +* [`asyncapi config context current`](#asyncapi-config-context-current) +* [`asyncapi config context list`](#asyncapi-config-context-list) +* [`asyncapi config context remove CONTEXT-NAME`](#asyncapi-config-context-remove-context-name) +* [`asyncapi config context use CONTEXT-NAME`](#asyncapi-config-context-use-context-name) +* [`asyncapi config versions`](#asyncapi-config-versions) +* [`asyncapi convert [SPEC-FILE]`](#asyncapi-convert-spec-file) +* [`asyncapi diff OLD NEW`](#asyncapi-diff-old-new) +* [`asyncapi generate`](#asyncapi-generate) +* [`asyncapi generate fromTemplate ASYNCAPI TEMPLATE`](#asyncapi-generate-fromtemplate-asyncapi-template) +* [`asyncapi generate models LANGUAGE FILE`](#asyncapi-generate-models-language-file) +* [`asyncapi new`](#asyncapi-new) +* [`asyncapi new file`](#asyncapi-new-file) +* [`asyncapi new glee`](#asyncapi-new-glee) +* [`asyncapi new project`](#asyncapi-new-project) +* [`asyncapi optimize [SPEC-FILE]`](#asyncapi-optimize-spec-file) +* [`asyncapi start`](#asyncapi-start) +* [`asyncapi start studio`](#asyncapi-start-studio) +* [`asyncapi validate [SPEC-FILE]`](#asyncapi-validate-spec-file) + +## `asyncapi bundle` + +bundle one or multiple asyncapi documents and their references together. + +``` +USAGE + $ asyncapi bundle [-h] [-o ] [-r] [-b ] + +FLAGS + -b, --base= Path to the file which will act as a base. This is required when some properties are + to needed to be overwritten. + -h, --help Show CLI help. + -o, --output= The output file name. Omitting this flag the result will be printed in the console. + -r, --reference-into-components Bundle the message $refs into components object. + +DESCRIPTION + bundle one or multiple asyncapi documents and their references together. + +EXAMPLES + $ asyncapi bundle ./asyncapi.yaml > final-asyncapi.yaml + + $ asyncapi bundle ./asyncapi.yaml --output final-asyncapi.yaml + + $ asyncapi bundle ./asyncapi.yaml ./features.yaml --reference-into-components + + $ asyncapi bundle ./asyncapi.yaml ./features.yaml --base ./asyncapi.yaml --reference-into-components +``` + +_See code: [src/commands/bundle.ts](https://github.com/asyncapi/cli/blob/v0.48.5/src/commands/bundle.ts)_ + +## `asyncapi config` + +CLI config settings + +``` +USAGE + $ asyncapi config + +DESCRIPTION + CLI config settings +``` + +_See code: [src/commands/config/index.ts](https://github.com/asyncapi/cli/blob/v0.48.5/src/commands/config/index.ts)_ + +## `asyncapi config context` + +``` +USAGE + $ asyncapi config context +``` + +## `asyncapi config context add CONTEXT-NAME SPEC-FILE-PATH` + +Add or modify a context in the store + +``` +USAGE + $ asyncapi config context add CONTEXT-NAME SPEC-FILE-PATH [-h] + +ARGUMENTS + CONTEXT-NAME context name + SPEC-FILE-PATH file path of the spec file + +FLAGS + -h, --help Show CLI help. + +DESCRIPTION + Add or modify a context in the store +``` + +## `asyncapi config context current` + +Shows the current context that is being used + +``` +USAGE + $ asyncapi config context current [-h] + +FLAGS + -h, --help Show CLI help. + +DESCRIPTION + Shows the current context that is being used +``` + +## `asyncapi config context list` + +List all the stored context in the store + +``` +USAGE + $ asyncapi config context list [-h] + +FLAGS + -h, --help Show CLI help. + +DESCRIPTION + List all the stored context in the store +``` + +## `asyncapi config context remove CONTEXT-NAME` + +Delete a context from the store + +``` +USAGE + $ asyncapi config context remove CONTEXT-NAME [-h] + +ARGUMENTS + CONTEXT-NAME Name of the context to delete + +FLAGS + -h, --help Show CLI help. + +DESCRIPTION + Delete a context from the store +``` + +## `asyncapi config context use CONTEXT-NAME` + +Set a context as current + +``` +USAGE + $ asyncapi config context use CONTEXT-NAME [-h] + +ARGUMENTS + CONTEXT-NAME name of the saved context + +FLAGS + -h, --help Show CLI help. + +DESCRIPTION + Set a context as current +``` + +## `asyncapi config versions` + +Show versions of AsyncAPI tools used + +``` +USAGE + $ asyncapi config versions [-h] + +FLAGS + -h, --help Show CLI help. + +DESCRIPTION + Show versions of AsyncAPI tools used +``` + +## `asyncapi convert [SPEC-FILE]` + +Convert asyncapi documents older to newer versions + +``` +USAGE + $ asyncapi convert [SPEC-FILE] [-h] [-o ] [-t ] + +ARGUMENTS + SPEC-FILE spec path, url, or context-name + +FLAGS + -h, --help Show CLI help. + -o, --output= path to the file where the result is saved + -t, --target-version= [default: 2.6.0] asyncapi version to convert to + +DESCRIPTION + Convert asyncapi documents older to newer versions +``` + +_See code: [src/commands/convert.ts](https://github.com/asyncapi/cli/blob/v0.48.5/src/commands/convert.ts)_ + +## `asyncapi diff OLD NEW` + +Find diff between two asyncapi files + ``` +USAGE + $ asyncapi diff OLD NEW [-h] [-f json|yaml|yml] [-t breaking|non-breaking|unclassified|all] [-o ] + [--no-error] [-w] [--log-diagnostics] [--diagnostics-format json|stylish|junit|html|text|teamcity|pretty] + [--fail-severity error|warn|info|hint] + +ARGUMENTS + OLD old spec path, URL or context-name + NEW new spec path, URL or context-name + +FLAGS + -f, --format=