-
Notifications
You must be signed in to change notification settings - Fork 127
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: updated commands documentation (issue 1429) and minor corrections. #1560
base: main
Are you sure you want to change the base?
Conversation
|
…ions, ran prettier
Ran prettier on the commands md files. |
Hi @lornajane, docs PR still awaiting review and approval from Redocly/technical-writers. Thanks in advance. |
Thanks @dianacheung ! I see it and it's on my list, we will review when we can. |
|
||
```bash | ||
redocly build-docs openapi.yaml | ||
``` | ||
|
||
In this case, the `build-docs` command builds the API at the path provided. | ||
In this case, the `build-docs` command builds the API description that was passed to the command. | ||
The configuration file is ignored. |
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.
The configuration file is ignored. | |
Even if a configuration file exists, the command does not check for APIs listed in it. |
|
||
```yaml Configuration file | ||
apis: | ||
games@v1: | ||
root: ./openapi/api-description.json | ||
``` | ||
|
||
The `build-docs` command uses any additional configurations provided in the file. | ||
You can generate a build by giving the API alias name, as shown below: |
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.
You can generate a build by giving the API alias name, as shown below: | |
You can generate a build by including the API name with the command, as in the following example: |
``` | ||
|
||
In this case, after resolving the path behind the `games@v1` name, `build-docs` generates a build of the `api-description.json` file. For this approach, the Redocly configuration file is mandatory. | ||
Any additional configurations provided in the file are used by the command. |
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.
Any additional configurations provided in the file are used by the command. | |
Any additional configurations provided in the file are also used by the command. |
|
||
### Custom configuration file | ||
### Use custom configuration file |
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.
### Use custom configuration file | |
### Use alternative file path |
|
||
By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.md) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file. | ||
|
||
```bash | ||
redocly build-docs --config=./another/directory/config.yaml | ||
``` | ||
|
||
### `theme.openapi` example | ||
### Use theme.openapi option |
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.
### Use theme.openapi option | |
### Hide search |
|
||
Build docs with hidden search box: | ||
The following command uses the optional `--theme.openapi` argument to build docs with hidden search box: |
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.
The following command uses the optional `--theme.openapi` argument to build docs with hidden search box: | |
The following command uses the optional `--theme.openapi` argument to build docs with the search box hidden: |
|
||
```bash | ||
redocly build-docs openapi.yaml --theme.openapi.disableSearch | ||
``` | ||
|
||
### `templateOptions` example | ||
### Use templateOptions option |
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.
### Use templateOptions option | |
### Use a custom template |
|
||
Build docs using a custom Handlebars template and add custom `templateOptions`: | ||
The following command uses the optional `--templateOptions` argument to build docs using a custom Handlebars template and add a custom `templateOptions` object: |
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.
The following command uses the optional `--templateOptions` argument to build docs using a custom Handlebars template and add a custom `templateOptions` object: | |
The following command builds docs using a custom Handlebars template and adds metadata to the meta tag in the head of the page using `templateOptions`: |
@@ -73,7 +77,7 @@ redocly bundle --dereferenced --output dist --ext json openapi/openapi.yaml open | |||
JSON output only works when there are no circular references. | |||
{% /admonition %} | |||
|
|||
### Custom configuration file | |||
### Use custom configuration file |
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.
### Use custom configuration file | |
### Use alternative file path |
| --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`. Default value is `error`. | | ||
|
||
## Examples | ||
|
||
### Default configuration file | ||
### Use default configuration file |
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.
### Use default configuration file | |
### Use default location for configuration file |
|
||
By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.md) in the current working directory. | ||
|
||
```bash | ||
redocly check-config | ||
``` | ||
|
||
### Custom configuration file | ||
### Use custom configuration file |
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.
### Use custom configuration file | |
### Use alternative filepath |
@@ -14,13 +14,15 @@ The output is a script for you to copy and paste, and add to the configuration f | |||
|
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.
hmm, for some reason this file is not included in the sidebar navigation menu. I will need to check with team to find out why. @Redocly/dark-side
From a bash prompt: | ||
### See bash shell example | ||
|
||
From a bash prompt, use the `completion` command: |
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.
From a bash prompt, use the `completion` command: | |
To generate an autocompletion script, run the following command from a bash or zsh prompt: |
|
||
```bash | ||
redocly completion | ||
``` | ||
|
||
Outputs something like this: | ||
Outputs the following script: |
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.
Outputs the following script: | |
If run from a bash prompt, the `completion` command outputs the following autocompletion script: |
{% /admonition %} | ||
|
||
### prefix-tags-with-info-prop | ||
### Use prefix-tags-with-info-prop option |
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.
### Use prefix-tags-with-info-prop option | |
### Prefix tags with specified `info` property |
|
||
### prefix-tags-with-filename | ||
### Use prefix-tags-with-filename option |
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.
### Use prefix-tags-with-filename option | |
### Prefix tags with filename |
|
||
### without-x-tag-groups | ||
### Use without-x-tag-groups option | ||
|
||
If you have the same tags in multiple API descriptions, you can allow tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property is not created in the joined file. |
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.
If you have the same tags in multiple API descriptions, you can allow tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property is not created in the joined file. | |
If you have the same tags in multiple API descriptions, you can avoid tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property is not created in the joined file. |
|
||
### without-x-tag-groups | ||
### Use without-x-tag-groups option |
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.
### Use without-x-tag-groups option | |
### Avoid tag duplication |
|
||
### prefix-components-with-info-prop | ||
### Use prefix-components-with-info-prop option |
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.
### Use prefix-components-with-info-prop option | |
### Resolve conflicting component names |
|
||
### Custom output file | ||
### Specify custom output file |
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.
### Specify custom output file | |
### Specify alternative filepath |
|
||
## Examples | ||
|
||
{% tabs %} | ||
{% tab label="Successful login" %} | ||
### See successful login |
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.
### See successful login | |
### View successful login message |
|
||
{% /tab %} | ||
{% tab label="Failed login" %} | ||
### See failed login |
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.
### See failed login | |
### View failed login message |
@@ -21,7 +22,11 @@ redocly logout --version | |||
|
|||
## Examples | |||
|
|||
```bash | |||
### See successful logout |
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.
### See successful logout | |
### View successful logout message |
|
||
#### Pass api directly | ||
#### Pass API directly | ||
|
||
```bash | ||
redocly preview-docs openapi/openapi.yaml | ||
``` | ||
|
||
In this case, `preview-docs` previews the API description that was passed to the command. The configuration file is ignored. |
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.
In this case, `preview-docs` previews the API description that was passed to the command. The configuration file is ignored. | |
In this case, `preview-docs` previews the API description that was passed to the command. Even if a configuration file exists, it is ignored. |
|
||
### Custom configuration file | ||
### Use custom configuration file |
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.
### Use custom configuration file | |
### Use alternative filepath |
|
||
```bash | ||
<pre> |
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.
Why change from markdown syntax to html?
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.
@adamaltman this is the purpose of the issue. We had a lot of either commands in text, or a wall of repeated code samples. The brief is to differentiate between the user's input, and displayed output examples.
|
||
Must be used only in combination with the `--batch-size` option. | ||
|
||
### Batch Size | ||
### Specify batch size |
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.
### Specify batch size | |
### Determine how many pushes are performed per batch |
@@ -279,7 +286,7 @@ redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization= | |||
{% /tab %} | |||
{% /tabs %} | |||
|
|||
### Public | |||
### Use public option |
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.
### Use public option | |
### Make API descriptions publicly accessible |
@@ -288,15 +295,15 @@ For more information on how to configure access to your APIs, check the [registr | |||
redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org --public | |||
``` | |||
|
|||
### Files | |||
### Use files option |
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.
### Use files option | |
### Upload other folders and files |
|
||
The `--files` option allows you to upload other folders and files. | ||
|
||
```bash | ||
redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org --files ./path/to/folder | ||
``` | ||
|
||
You can also add files and folders providing them in `redocly.yaml`: | ||
You can also add files and folders by providing them in `redocly.yaml` configuration file: |
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.
You can also add files and folders by providing them in `redocly.yaml` configuration file: | |
You can also add files and folders by providing them in the `redocly.yaml` configuration file: |
@@ -308,12 +315,12 @@ files: | |||
- ./file.md | |||
``` | |||
|
|||
**`--files` has higher priority than `redocly.yaml`** | |||
Note that `--files` has higher priority than `redocly.yaml`. |
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.
Note that `--files` has higher priority than `redocly.yaml`. | |
Note that the `--files` option has higher priority than the `redocly.yaml` configuration file. |
|
||
{% tabs %} | ||
{% tab label="Command" %} | ||
### See successful split |
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.
### See successful split | |
### View successful split message |
|
||
You can use the `stats` command with an OpenAPI description directly, with a command like the following: | ||
|
||
```bash | ||
redocly stats openapi/openapi.yaml | ||
``` | ||
|
||
In this case, `stats` shows statistics for the API description that was passed to the command. | ||
In this case, `stats` shows statistics for the API description that was passed in. The configuration file is ignored. |
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.
In this case, `stats` shows statistics for the API description that was passed in. The configuration file is ignored. | |
In this case, `stats` shows statistics for the API description that was passed in. Even if the configuration file exists, it is ignored. |
|
||
### Custom configuration file | ||
### Use custom configuration file |
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.
### Use custom configuration file | |
### Use alternative filepath |
|
||
By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.md) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file. | ||
|
||
```bash | ||
redocly stats --config=./another/directory/config.yaml | ||
``` | ||
|
||
### Format | ||
### Specify output format | ||
|
||
#### Stylish (default) |
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.
#### Stylish (default) | |
#### Specify the stylish (default) output format |
|
||
You can use the JSON output to pass to another program. | ||
The JSON format output is suitable when you want to use the stats data in another program. | ||
|
||
#### Markdown |
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.
#### Markdown | |
#### Specify the Markdown output format |
|
||
In this format, `stats` shows the statistics in condensed but readable output with colored text and an icon at the beginning of each line. | ||
In this format, `stats` shows the statistics in a condensed but readable manner with an icon at the beginning of each line. | ||
|
||
#### JSON |
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.
#### JSON | |
#### Specify the JSON output format |
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.
Hi @dianacheung - you have made some great updates with this PR. Thank you for your contribution. I made a few suggestions I would like you to take a look at. Thanks!
Hi @HCloward and @lornajane, thanks for reviewing and providing feedback. I'm out of office for rest of May and plan to pick this PR back up around mid June. I will reach out with any follow up questions on the feedback. Appreciate your patience. |
What/Why/How?
Updated commands documentation per issue 1429 and also made minor changes for correction and consistency.
Reference
#1429
Testing
Ran redocly preview for local development.
Ran spelling check.
Ran vale.
Ran mlc.
Ran markdownlint.