-
-
Notifications
You must be signed in to change notification settings - Fork 215
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: add new Usage document #842
Merged
Merged
Changes from 32 commits
Commits
Show all changes
33 commits
Select commit
Hold shift + click to select a range
542889e
add asyncapiDocument and asyncapiString documentation
Florence-Njeri be026ef
copy usage from the Readme
Florence-Njeri b30aa8e
add ids
Florence-Njeri cbfc1a0
remove the spec file from this PR
Florence-Njeri e273f74
add this document is under construction note
Florence-Njeri 9066968
refactor and improve the usage docs
Florence-Njeri 7a8c3df
fix page weight and fix grammar
Florence-Njeri a3f86e2
refactor generator library
Florence-Njeri 7630ecf
remove usage from readme and link the usage docs in the ReadME
Florence-Njeri 6381ea5
Update docs/usage.md
Florence-Njeri 6d70e3b
Update docs/usage.md
Florence-Njeri 8699e4c
Update docs/usage.md
Florence-Njeri a539675
Update docs/usage.md
Florence-Njeri 5919ced
remove ag command that's been replaced by asyncapi generate fromTemplate
Florence-Njeri aa3ff85
pulled from remote origin
Florence-Njeri b188d66
change AsyncAPI file to AsyncAPI document
Florence-Njeri 508fceb
Update README.md
Florence-Njeri 4dd1eac
Update README.md
Florence-Njeri 707dd30
Update docs/usage.md
Florence-Njeri 176643d
Update docs/usage.md
Florence-Njeri ec56eb2
convert all references of the generator to lowercase
Florence-Njeri aebd16d
remove manual addition of usage to the TOC
Florence-Njeri d24c1df
update internal link
Florence-Njeri ef448df
lowercase generator
Florence-Njeri c69a008
remove linking to templates.md in code section
Florence-Njeri 2d36d24
remove usage section from readme.md
Florence-Njeri 6110bb9
grammarly
Florence-Njeri 1289415
update TOC
Florence-Njeri d378734
Merge branch 'master' into usage
derberg f781c1b
Merge branch 'master' into usage
Florence-Njeri ee92c27
Merge branch 'master' into usage
Florence-Njeri c962245
Merge branch 'master' into usage
derberg 540dfbd
Merge branch 'master' into usage
derberg File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,153 @@ | ||
--- | ||
title: "Usage" | ||
weight: 30 | ||
--- | ||
|
||
There are two ways to use the generator: | ||
- [Generator CLI](#generator-cli) | ||
- [Generator library](#generator-library) | ||
|
||
## Generator CLI | ||
```bash | ||
Usage: asyncapi generate fromTemplate <asyncapi> <template> [<options>] | ||
|
||
- <asyncapi>: Local path or URL pointing to AsyncAPI document for example https://bit.ly/asyncapi | ||
- <template>: Name of the generator template like for example @asyncapi/html-template or https://github.com/asyncapi/html-template | ||
|
||
- <options>: | ||
-V, --version output the generator version | ||
-d, --disable-hook [hooks...] disable a specific hook type or hooks from a given hook type | ||
--debug enable more specific errors in the console | ||
-i, --install install the template and its dependencies (defaults to false) | ||
-n, --no-overwrite <glob> glob or path of the file(s) to skip when regenerating | ||
-o, --output <outputDir> directory to put the generated files (defaults to current directory) | ||
-p, --param <name=value> additional parameters to pass to templates | ||
--force-write force writing of the generated files to a given directory even if it is a Git repository with unstaged files or not empty dir (defaults to false) | ||
--watch-template watches the template directory and the AsyncAPI document, and re-generates the files when changes occur. Ignores the output directory. This flag should be used only for template development. | ||
--map-base-url <url:folder> maps all schema references from base URL to local folder | ||
-h, --help display help for command | ||
``` | ||
|
||
<details> | ||
<summary>Click here to read more about supported values for the <code><template></code> parameter.</summary> | ||
<br> | ||
All templates are installable npm packages. Therefore, the value of <code><template></code> can be anything supported by <code>npm install</code>. Here's a summary of the possibilities: | ||
<br><br> | ||
<pre><code> | ||
npm install [<@scope>/]<name> | ||
npm install [<@scope>/]<name>@<tag> | ||
npm install [<@scope>/]<name>@<version> | ||
npm install [<@scope>/]<name>@<version range> | ||
npm install <git-host>:<git-user>/<repo-name> | ||
npm install <git repo url> | ||
npm install <tarball file> | ||
npm install <tarball url> | ||
npm install <folder></code></pre> | ||
</details> | ||
<br> | ||
|
||
### Global templates installed with `yarn` or `npm` | ||
|
||
You can preinstall templates globally before installing the generator CLI. The generator first tries to locate the template in local dependencies; if absent it checks where the global generator packages are installed. | ||
|
||
```bash | ||
npm install -g @asyncapi/html-template@0.16.0 | ||
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template | ||
# The generator uses html-template version 0.16.0 and not the latest version. | ||
``` | ||
|
||
### CLI usage examples | ||
|
||
**The shortest possible syntax:** | ||
```bash | ||
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template | ||
``` | ||
|
||
**Generating from a URL:** | ||
```bash | ||
asyncapi generate fromTemplate https://bit.ly/asyncapi @asyncapi/html-template | ||
``` | ||
|
||
**Specify where to put the result:** | ||
```bash | ||
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs | ||
``` | ||
|
||
**Passing parameters to templates:** | ||
```bash | ||
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs -p title='Hello from param' | ||
``` | ||
|
||
In the template you can use it like this: ` {{ params.title }}` | ||
|
||
**Disabling the hooks:** | ||
```bash | ||
asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs -d generate:before generate:after=foo,bar | ||
``` | ||
|
||
The generator skips all hooks of the `generate:before` type and `foo`, `bar` hooks of the `generate:after` type. | ||
|
||
**Installing the template from a folder:** | ||
```bash | ||
asyncapi generate fromTemplate asyncapi.yaml ~/my-template | ||
``` | ||
|
||
It creates a symbolic link to the target directory (`~/my-template` in this case). | ||
|
||
**Installing the template from a git URL:** | ||
```bash | ||
asyncapi generate fromTemplate asyncapi.yaml https://github.com/asyncapi/html-template.git | ||
``` | ||
|
||
**Map schema references from baseUrl to local folder:** | ||
```bash | ||
asyncapi generate fromTemplate test/docs/apiwithref.json @asyncapi/html-template -o ./build/ --force-write --map-base-url https://schema.example.com/crm/:./test/docs/ | ||
``` | ||
|
||
The parameter `--map-base-url` maps external schema references to local folders. | ||
|
||
### CLI usage with Docker | ||
|
||
When using our docker image that we regularly update, you don't need to install Node.js or Npm, even though the generator is written with it since the Docker image has the generator installed. | ||
|
||
Install [Docker](https://docs.docker.com/get-docker/) first, then use docker to pull and run the image using the following command: | ||
|
||
```bash | ||
docker run --rm -it \ | ||
-v [ASYNCAPI SPEC FILE LOCATION]:/app/asyncapi.yml \ | ||
-v [GENERATED FILES LOCATION]:/app/output \ | ||
asyncapi/generator [COMMAND HERE] | ||
|
||
# Example that you can run inside the generator 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 \ | ||
-v ${PWD}/test/docs/dummy.yml:/app/asyncapi.yml \ | ||
-v ${PWD}/output:/app/output \ | ||
asyncapi/generator -o /app/output /app/asyncapi.yml @asyncapi/html-template --force-write | ||
``` | ||
|
||
### CLI usage with `npx` instead of `npm` | ||
|
||
[npx](https://www.npmjs.com/package/npx) is very useful when you want to run the generator in a CI/CD environment. In such a scenario, do not install the generator globally because most environments that provide Node.js and Npm, also provide npx out of the box. | ||
|
||
Use the following npx command on your terminal: | ||
|
||
```bash | ||
npx -p @asyncapi/cli asyncapi generate fromTemplate ./asyncapi.yaml @asyncapi/html-template | ||
``` | ||
|
||
## Using as a module/package | ||
Once you install the generator in your project, you can use it to generate whatever you want. The following code snippet is an example of HTML generation using the official `@asyncapi/html-template` template and fetching the spec document from the server using `https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml`: | ||
|
||
```js | ||
const path = require('path'); | ||
const generator = new Generator('@asyncapi/html-template', path.resolve(__dirname, 'example')); | ||
|
||
try { | ||
await generator.generateFromURL('https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml'); | ||
console.log('Done!'); | ||
} catch (e) { | ||
console.error(e); | ||
} | ||
``` | ||
|
||
See the [API documentation](api.md) for more examples and full API reference information. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hey @Florence-Njeri, consistency is key 🔑 😄. If you don't normally capitalize
generator
so far in these docs (as I also noted in PR #818), let's keep that consistent.📢 ACTION ITEM: Please go through this entire PR and correct all your capitalized mentions of
generator
to lowercase so that the Docs are consistent.