LukeParke/redocly-cli
1
0
Fork 0
mirror of https://github.com/LukeHagar/redocly-cli.git synced 2025-12-06 04:21:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update commands documentation (issue 1429) and minor corrections (#1560)

Browse Source 
* docs: updated commands documentation per issue 1429 and minor corrections, ran prettier

* docs: updated commands documentation per issue 1429 and included pr 1560 feedback

* docs: minor formatting and copyedits

---------

Co-authored-by: Diana Cheung <18452752+dianacheung@users.noreply.github.com>
Co-authored-by: Lorna Mitchell <lorna.mitchell@redocly.com>
This commit is contained in:
dianacheung
2024-07-05 12:59:59 -07:00
committed by GitHub
parent a4adc7a175
commit 4c3d8cf84f
14 changed files with 433 additions and 367 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
docs/commands/build-docs.md
View File

@@ -2,7 +2,8 @@
## Introduction
The `build-docs` command builds Redoc into an HTML file.
The `build-docs` command builds Redoc into an HTML file that contains your API documentation.
The standalone HTML file can be easily shared or hosted on a platform of your choice.
## Usage
@@ -16,42 +17,39 @@ redocly build-docs <api> -t custom.hbs --templateOptions.metaDescription "Page m
## Options
| Option | Type | Description |
| ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api | string | Path to the API description filename or alias that you want to generate the build for. Refer to the [API examples](#api-examples) for more information.<br/> |
| --config | string | Specifies path to the [configuration file](#custom-configuration-file). |
| --disableGoogleFont | boolean | Disables Google fonts. The default value is false. |
| --help | boolean | Shows help. |
| --lint-config | string | Specify the severity level for the configuration file. Possible values: warn, error, off. Default value is warn |
| --output, -o | string | Sets the path and name of the output file. The default value is redoc-static.html. |
| --template, -t | string | Uses custom [Handlebars](https://handlebarsjs.com/) templates to render your OpenAPI description. |
| --templateOptions | string | Adds template options you want to pass to your custom Handlebars template. To add options, use dot notation. |
| --theme.openapi | string | Customizes your output with [Redoc functionality options](https://redocly.com/docs/api-reference-docs/configuration/functionality/) or [Redoc theming options](https://redocly.com/docs/api-reference-docs/configuration/theming/). |
| --title | string | Sets the page title. |
| --version | boolean | Shows version number. |
| Option | Type | Description |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api | string | Path to the API description filename or alias that you want to generate the build for. Refer to [the API section](#specify-api) for more details. |
| --config | string | Path to the [configuration file](#use-an-alternative-configuration-file). Defaults to `redocly.yaml` in the local folder. |
| --disableGoogleFont | boolean | Disable Google fonts. The default value is `false`. |
| --help | boolean | Show help. |
| --lint-config | string | Specify the severity level for the configuration file. Possible values: `warn`, `error`, `off`. Default value is `warn`. |
| --output, -o | string | Set the path and name of the output file. The default value is `redoc-static.html`. |
| --template, -t | string | Use custom [Handlebars](https://handlebarsjs.com/) templates to render your OpenAPI description. |
| --templateOptions | string | Add template options you want to pass to your custom Handlebars template. To add options, use dot notation. |
| --theme.openapi | string | Customize your output with [Redoc functionality options](https://redocly.com/docs/api-reference-docs/configuration/functionality/) or [Redoc theming options](https://redocly.com/docs/api-reference-docs/configuration/theming/). |
| --title | string | Set the page title. |
| --version | boolean | Show version number. |
## Examples
### API examples
### Specify API
The command accepts an API positional argument as either a file (no configuration file is required) or an alias (requires a [configuration file](#custom-configuration-file)).
The `build-docs` command behaves differently depending on how you pass the API to it, and whether the [configuration file](#use-an-alternative-configuration-file) exists.
#### API path to file example
#### Pass an API directly
```bash
redocly build-docs openapi.yaml
```
In this case, the `build-docs` command builds the API at the path provided.
The configuration file is ignored.
In this case, the `build-docs` command builds the API description that was passed to the command.
Even if a configuration file exists, the command does not check for APIs listed in it.
#### API alias example
#### Pass an API alias
Instead of a full path, you can use an API name from the `apis` object of your Redocly configuration file.
```bash Command
redocly build-docs games@v1
```
For example, with a `redocly.yaml` configuration file containing the following entry for `games@v1`:
```yaml Configuration file
apis:
@@ -59,9 +57,16 @@ apis:
root: ./openapi/api-description.json
```
The `build-docs` command uses any additional configurations provided in the file.
You can generate a build by including the API name with the command, as shown in the following example:
### Custom configuration file
```bash Command
redocly build-docs games@v1
```
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 also used by the command.
### Use an alternative configuration file
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.
@@ -69,23 +74,23 @@ By default, the CLI tool looks for the [Redocly configuration file](../configura
redocly build-docs --config=./another/directory/config.yaml
```
### `theme.openapi` example
### Hide search
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 a custom template
Build docs using a custom Handlebars template and add custom `templateOptions`:
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`:
```bash
redocly build-docs ./openapi/api.yaml -t custom.hbs --templateOptions.metaDescription "Page meta description"
```
Sample Handlebars template:
Sample custom Handlebars template:
```handlebars
<html>

14
docs/commands/bundle.md
View File

@@ -4,7 +4,9 @@
API descriptions can grow and become difficult to manage, especially if several teams are collaborating on them. It's a good practice to maintain the reusable parts as separate files, and include them in the main (root) API description by referencing them with `$ref`. However, most OpenAPI tools don't support that multi-file approach, and require a single-file API description.
Redocly CLI can help you combine separate API description files (such as if you used the `split` command) into one. The `bundle` command pulls the relevant parts of an API description into a single file output in JSON or YAML format.
Redocly CLI can help you combine separate API description files (such as if you used the [`split`](./split.md) command) into one. The `bundle` command pulls the relevant parts of an API description into a single file output in JSON or YAML format.
The `bundle` command differs from the [`join`](./join.md) command. The `bundle` command takes a root OpenAPI file as input and follows the `$ref` mentions to include all the referenced components into a single output file. The `join` command can combine multiple OpenAPI files into a single unified API description file.
The `bundle` command first executes preprocessors, then rules, then decorators.
@@ -23,7 +25,7 @@ redocly bundle --version
| Option | Type | Description |
| -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apis | [string] | List of API description root filenames or names assigned in the `apis` section of your Redocly configuration file. Default values are all names defined in the `apis` section within your configuration file. |
| --config | string | Specify path to the [config file](#custom-configuration-file). |
| --config | string | Specify path to the [configuration file](#use-alternative-configuration-file). |
| --dereferenced, -d | boolean | Generate fully dereferenced bundle. |
| --ext | string | Specify bundled file extension. Possible values are `json`, `yaml`, or `yml`. Default value is `yaml`. |
| --extends | [string] | Can be used in combination with `--lint` to [extend a specific configuration](./lint.md#extend-configuration). Default values are taken from the Redocly configuration file. |
@@ -56,10 +58,12 @@ This command creates one bundled file for each of the specified apis in the `dis
redocly bundle --output dist --ext json openapi/openapi.yaml openapi/museum.yaml
```
```bash Output
The `dist/` folder contents after the `bundle` command is executed:
<pre>
dist/openapi.json
dist/museum.json
```
</pre>
### Create a fully dereferenced bundle
@@ -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 alternative configuration file
By default, the CLI tool looks for the Redocly configuration file in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.

8
docs/commands/check-config.md
View File

@@ -2,7 +2,7 @@
## Introduction
Use this command to check that everything in a Redocly configuration file is valid and in the expected format.
Use the `check-config` command to check that the content in a Redocly configuration file is valid and in the expected format.
Adding this check before using the configuration file with other commands can catch any problems at an early stage.
This command uses the same mechanism as our API linting to match a file against an expected data structure.
@@ -17,12 +17,12 @@ redocly check-config [--config=<path>]
| Option | Type | Description |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| --config | string | Specify path to the [config file](#custom-configuration-file). |
| --config | string | Specify path to the [configuration file](#use-alternative-configuration-file). |
| --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 location for configuration file
By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.md) in the current working directory.
@@ -30,7 +30,7 @@ By default, the CLI tool looks for the [Redocly configuration file](../configura
redocly check-config
```
### Custom configuration file
### Use alternative configuration file
Use the optional `--config` argument to provide an alternative path to a configuration file.

12
docs/commands/completion.md
View File

@@ -14,13 +14,15 @@ The output is a script for you to copy and paste, and add to the configuration f
## Examples
From a bash prompt:
### See bash shell example
To generate an autocompletion script, run the following command from a bash or zsh prompt:
```bash
redocly completion
```
Outputs something like this:
If run from a bash prompt, the `completion` command outputs the following autocompletion script:
```sh
###-begin-redocly-completions-###
@@ -53,9 +55,9 @@ complete -o default -F _redocly_yargs_completions redocly
###-end-redocly-completions-###
```
The installation instructions are included in the output, showing how to run the command and add it to the correct file:
The installation instructions are included in the output as comments, showing how to run the command and add it to the correct file:
- `redocly completion >> ~/.bashrc`
- or on OSX: `redocly completion >> ~/.bash_profile`
- Or on OSX: `redocly completion >> ~/.bash_profile`
Users of zsh receive similar output appropriate for their system.
If you use zsh shell, the `completion` command provides a similar output that is appropriate for your system.

7
docs/commands/index.md
View File

@@ -12,7 +12,7 @@ Documentation commands:
API management commands:
- [`stats`](stats.md) Gathering statistics for a document.
- [`stats`](stats.md) Gather statistics for a document.
- [`bundle`](bundle.md) Bundle API description.
- [`split`](split.md) Split API description into a multi-file structure.
- [`join`](join.md) Join API descriptions [experimental feature].
@@ -20,6 +20,7 @@ API management commands:
Linting commands:
- [`lint`](lint.md) Lint API description.
- [`check-config`](check-config.md) Lint Redocly configuration file.
Redocly platform commands:
@@ -35,9 +36,9 @@ Supporting commands:
There are some parameters supported by all commands:
`--version` displays the current version of `redocly`.
`--version` display the current version of `redocly`.
`--help` displays the command help, or the help for the subcommand if you used one. For example:
`--help` display the command help, or the help for the subcommand if you used one. For example:
```bash
redocly lint --help

122
docs/commands/join.md
View File

@@ -8,22 +8,20 @@ The `join` command is considered an experimental feature. This means it's still
The `join` command supports OpenAPI 3.x descriptions only.
{% /admonition %}
Maintainers of multiple API descriptions can benefit from storing each endpoint as a standalone API description file. However, this approach is not supported by the majority of OpenAPI tools, as they require a single API description file.
Maintainers of multiple API descriptions can benefit from storing each endpoint as a standalone API description file. However, this approach is not supported by the majority of OpenAPI tools, as they require a single API description file. With Redocly CLI, you can solve this problem by using the `join` command to combine two or more API description files into a single one.
With Redocly CLI, you can solve this problem by using the `join` command that can combine two or more API description files into a single one.
The `join` command differs from the [`bundle`](./bundle.md) command. The `bundle` command takes a root OpenAPI file as input and follows the `$ref` mentions to include all the referenced components into a single output file. The `join` command can combine multiple OpenAPI files into a single unified API description file.
To easily distinguish the origin of OpenAPI objects and properties, you can optionally instruct the `join` command to append custom prefixes to them.
To easily distinguish the origin of OpenAPI objects and properties, you can optionally instruct the `join` command to prepend custom prefixes to them.
The `join` command accepts both YAML and JSON files, which you can mix in the resulting `openapi.yaml` or `openapi.json` file. Setting a custom name and extension for this file can be achieved by providing it through the `--output` argument. Any existing file is overwritten. If the `--output` option is not provided, the command uses the extension of the first entry point file.
Apart from providing individual API description files as the input, you can also specify the path to a folder that contains multiple API description files and match them with a wildcard (for example, `myproject/openapi/*.(yaml/json)`). The `join` command collects all matching files and combines them into one file.
{% admonition type="info" name="Use join with other commands" %}
We recommend running [`lint`](./lint.md) before joining API descriptions to ensure that they are valid and meet the expected standards.
You may also want to use [decorators](./../decorators.md) to add any filtering or transformation needed for your API descriptions, either before or after bundling.
{% /admonition %}
You may also want to use [decorators](./../decorators.md) to add any filtering or transformation needed for your API descriptions, either before or after combining.
### Usage
## Usage
```bash
redocly join <api> <api>...
@@ -39,42 +37,38 @@ redocly join --version
## Options
| Option | Type | Description |
| ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apis | [string] | **REQUIRED.** 1. Array of paths to API description files that you want to join. At least two input files are required.<br />2. A wildcard pattern to match API description files within a specific folder. |
| --config | string | Specify path to the [config file](../configuration/index.md). |
| --help | boolean | Show help. |
| --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
| --output, -o | string | Name for the joined output file. Defaults to `openapi.yaml` or `openapi.json` (Depends on the extension of the first input file). **If the file already exists, it's overwritten.** |
| --prefix-components-with-info-prop | string | Prefix components with property value from info object. See the [prefix-components-with-info-prop section](#prefix-components-with-info-prop) below. |
| --prefix-tags-with-filename | string | Prefix tags with property value from file name. See the [prefix-tags-with-filename section](#prefix-tags-with-filename) below. |
| --prefix-tags-with-info-prop | boolean | Prefix tags with property value from info object. See the [prefix-tags-with-info-prop](#prefix-tags-with-info-prop) section. |
| --version | boolean | Show version number. |
| --without-x-tag-groups | boolean | Skip automated `x-tagGroups` creation. See the [without-x-tag-groups](#without-x-tag-groups) section. |
| Option | Type | Description |
| ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| apis | [string] | **REQUIRED.** 1. Array of paths to API description files that you want to join. At least two input files are required.<br />2. A wildcard pattern to match API description files within a specific folder. |
| --config | string | Specify path to the [configuration file](../configuration/index.md). |
| --help | boolean | Show help. |
| --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
| --output, -o | string | Name for the joined output file. Defaults to `openapi.yaml` or `openapi.json` (depends on the extension of the first input file). **If the file already exists, it's overwritten.** See the [specify output file](#specify-output-file) section. |
| --prefix-components-with-info-prop | string | Prefix components with property value from info object. See the [resolve conflicting component names](#resolve-conflicting-component-names) section. |
| --prefix-tags-with-filename | boolean | Prefix tags with property value from file name. See the [prefix tags with filename](#prefix-tags-with-filename) section. |
| --prefix-tags-with-info-prop | string | Prefix tags with property value from info object. See the [prefix tags with specified info property](#prefix-tags-with-specified-info-property) section. |
| --version | boolean | Show version number. |
| --without-x-tag-groups | boolean | Skip automated `x-tagGroups` creation. See the [avoid tag duplication](#avoid-tag-duplication) section. |
{% admonition type="warning" %}
These options are mutually exclusive: `without-x-tag-groups`, `prefix-tags-with-filename`, and `prefix-tags-with-info-prop`.
{% /admonition %}
## Examples
### Array of paths
### Specify an array of paths
**Command**
This command combines the API description files that are passed in:
```bash
redocly join first-api.yaml second-api.json
```
**Output**
```bash
redocly join first-api.yaml second-api.json
openapi.yaml: join processed in 56ms
```
The command creates the output `openapi.yaml` file in the working directory.
The output file `openapi.yaml` is created in the working directory:
The order of input files affects how their content is processed. The first provided file is always treated as the "main" file, and its content has precedence over other input files when combining them. Specifically, the following properties of the API description are always taken only from the first input file:
```yaml
<pre>
info:
version
title
@@ -82,13 +76,13 @@ info:
contact
license
externalDocs
```
</pre>
By default, the `info.description` property is taken only from the first file, even if it exists in other input files.
However, if any of the input files contain the `tags` object, the `join` command automatically creates the `x-tagGroups` object in the output file.
```yaml
<pre>
x-tagGroups:
- name: first-api
tags:
@@ -97,7 +91,9 @@ x-tagGroups:
- name: second-api
tags:
- partner
```
</pre>
Use the [`--without-x-tag-groups`](#avoid-tag-duplication) option to skip the creation and population of `x-tagGroups` in the output file.
{% admonition type="info" %}
If some operations in an input file don't have a tag assigned to them, the `join` command automatically adds the `other` tag to those operations in the output file. The `other` tag is also included in the `x-tagGroups` object.
@@ -114,7 +110,7 @@ Path names and component names must be unique in all input files, but their cont
If the `join` command detects any conflicting content while trying to combine the input files, it displays informative messages about the conflicts and exits without creating an output file. To prevent this, use optional parameters to add prefixes to tags and components.
```bash
<pre>
Conflict on tags => all : tickets in files: museum.yaml,exhibition.yaml
1 conflict(s) on tags.
@@ -128,31 +124,23 @@ Conflict on paths => operationIds : getEvent in files: museum.yaml,exhibition.ya
Conflict on paths => /tickets/{Id} : get in files: museum.yaml,exhibition.yaml
Please fix conflicts before running join.
```
</pre>
Use the [`--without-x-tag-groups`](#without-x-tag-groups) option to skip the creation and population of `x-tagGroups` in the output file.
{% admonition type="warning" %}
These options are mutually exclusive: `without-x-tag-groups`, `prefix-tags-with-filename`, and `prefix-tags-with-info-prop`.
{% /admonition %}
### prefix-tags-with-info-prop
### Prefix tags with specified `info` property
If any of the input files contain the `tags` object, tags in the output file are prefixed by the selected property from the `info` object of the corresponding input file.
The output file preserves the original tag names as the value of the `x-displayName` property for each tag.
#### Usage
**Command**
This command uses the `title` property as the prefix:
```bash
redocly join first-api.yaml second-api.json --prefix-tags-with-info-prop title
```
**Output file example**
The following is the example output:
```yaml
<pre>
- name: First Document title_endpoints
description: endpoints tag description
x-displayName: endpoints
@@ -160,25 +148,23 @@ redocly join first-api.yaml second-api.json --prefix-tags-with-info-prop title
- name: Second document title_events
description: events tag description
x-displayName: events
```
</pre>
### prefix-tags-with-filename
### Prefix tags with filename
If any of the input files contain the `tags` object, tags in the output file are prefixed by the filename of the corresponding input file.
The output file preserves the original tag names as the value of the `x-displayName` property for each tag.
#### Usage
**Command**
This command sets the `--prefix-tags-with-filename` option:
```bash
redocly join first-api.yaml second-api.json --prefix-tags-with-filename true
```
**Output file example**
The following is the example output:
```yaml
<pre>
- name: first-api_endpoints
description: endpoints tag description
x-displayName: endpoints
@@ -186,13 +172,13 @@ redocly join first-api.yaml second-api.json --prefix-tags-with-filename true
- name: second-api_events
description: events tag description
x-displayName: events
```
</pre>
### without-x-tag-groups
### Avoid tag duplication
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.
#### Usage
This command sets the `--without-x-tag-groups` option:
```bash Command
redocly join first-api.yaml second-api.json --without-x-tag-groups
@@ -200,27 +186,25 @@ redocly join first-api.yaml second-api.json --without-x-tag-groups
The tag description is taken from the first file that contains the tag. You may see a warning about conflicts in the command output:
```bash
<pre>
warning: 1 conflict(s) on tags description.
openapi.yaml: join processed in 69ms
```
</pre>
### prefix-components-with-info-prop
### Resolve conflicting component names
If any of the input files have conflicting component names, this option can be used to resolve that issue and generate the output file. All component names in the output file are prefixed by the selected property from the `info` object of the corresponding input file(s).
#### Usage
**Command**
This command uses the `version` property as the prefix:
```bash
redocly join museum_v1.yaml museum_v2.json --prefix-components-with-info-prop version
```
**Output file example**
The following is the example output:
```yaml
<pre>
components:
schemas:
1.0.0_BuyMuseumTicketsRequest:
@@ -268,9 +252,9 @@ components:
- ticketDate
- email
```
</pre>
### Custom output file
### Specify output file
By default, the CLI tool writes the joined file as `openapi.yaml` or `openapi.json` in the current working directory. Use the optional `--output` argument to provide an alternative output file path.

198
docs/commands/lint.md
View File

@@ -22,37 +22,43 @@ redocly lint --version
## Options
| Option | Type | Description |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| apis | [string] | Array of API description filenames that need to be linted. See [the Apis section](#apis) for more options. |
| --config | string | Specify path to the [configuration file](#custom-configuration-file). |
| --extends | [string] | [Extend a specific configuration](#extend-configuration) (defaults or config file settings). |
| --format | string | Format for the output.<br />**Possible values:** `codeframe`, `stylish`, `json`, `checkstyle`, `codeclimate`, `github-actions`, `markdown`, `summary`. Default value is `codeframe`. |
| --generate-ignore-file | boolean | [Generate ignore file](#generate-ignore-file). |
| --help | boolean | Show help. |
| --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
| --max-problems | integer | Truncate output to display the specified [maximum number of problems](#max-problems). Default value is 100. |
| --skip-preprocessor | [string] | Ignore certain preprocessors. See the [Skip preprocessor or rule section](#skip-preprocessor-or-rule) below. |
| --skip-rule | [string] | Ignore certain rules. See the [Skip preprocessor or rule section](#skip-preprocessor-or-rule) below. |
| --version | boolean | Show version number. |
| Option | Type | Description |
| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apis | [string] | Array of API description filenames that need to be linted. Refer to [the API section](#specify-api) for more details. |
| --config | string | Specify path to the [configuration file](#use-custom-configuration-file). |
| --extends | [string] | [Extend a specific configuration](#extend-configuration) (defaults or config file settings). **Possible values:** `minimal`, `recommended`, `recommended-strict`, `all`. Default value is `recommended`. |
| --format | string | Format for the output.<br />**Possible values:** `codeframe`, `stylish`, `json`, `checkstyle`, `codeclimate`, `github-actions`, `markdown`, `summary`. Default value is `codeframe`. |
| --generate-ignore-file | boolean | [Generate ignore file](#generate-ignore-file). |
| --help | boolean | Show help. |
| --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
| --max-problems | integer | Truncate output to display the specified [maximum number of problems](#limit-the-displayed-problems-count). Default value is `100`. |
| --skip-preprocessor | [string] | Ignore certain preprocessors. See the [Skip preprocessor or rule section](#skip-preprocessor-or-rule) below. |
| --skip-rule | [string] | Ignore certain rules. See the [Skip preprocessor or rule section](#skip-preprocessor-or-rule) below. |
| --version | boolean | Show version number. |
## Examples
### <a id="apis"></a>Lint APIs
### Specify API
The `lint` command behaves differently depending on how you pass apis to it and whether the [configuration file](#custom-configuration-file) exists.
The `lint` command behaves differently depending on how you pass the API(s) to it, and whether the [configuration file](#use-custom-configuration-file) exists.
#### Pass an API directly
#### Pass API directly
`redocly lint openapi/openapi.yaml`
```bash
redocly lint openapi/openapi.yaml
```
In this case, `lint` validates the API description(s) passed to the command. If you have no configuration file defined, the [recommended ruleset](../rules/recommended.md) is used. If you have `extends` or `rules` defined in `redocly.yaml`, those are used when linting.
In this case, `lint` validates the API description(s) passed to the command. If you have no configuration file defined, the [recommended ruleset](../rules/recommended.md) is used. If you have `extends` or `rules` defined in `redocly.yaml`, then those are used when linting.
The `apis` argument can also use any glob format supported by your file system. For example, `redocly lint ./root-documents/*.yaml`.
The `apis` argument can also use any glob format supported by your file system. For example:
#### An API from the configuration file
```bash
redocly lint ./root-documents/*.yaml
```
Instead of full paths, you can use names listed in the `apis` section of your Redocly configuration file. The example `redocly.yaml` file below shows an API alias `core@v1` defined:
#### Pass API alias
Instead of full paths, you can use names listed in the `apis` section of your Redocly configuration file. The example `redocly.yaml` configuration file below shows an API alias `core@v1` defined:
```yaml
apis:
@@ -62,13 +68,15 @@ apis:
Use the alias with the lint command as shown:
`redocly lint core@v1`
```bash
redocly lint core@v1
```
In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `lint` validates the `api-description.json` file. The presence of the Redocly configuration file is mandatory.
In this case, after resolving the path behind the `core@v1` name, `lint` validates the `api-description.json` file. For this approach, the Redocly configuration file is mandatory.
#### All configured APIs
#### Lint all configured APIs
You can omit apis completely when executing the `lint` command to check all APIs defined in the configuration file. Run `redocly lint` with no arguments to lint all defined APIs; an example `redocly.yaml` file is shown below:
You can omit the `apis` argument completely when executing the `lint` command to check all APIs defined in the configuration file. Run `redocly lint` with no arguments to lint all defined APIs. An example `redocly.yaml` file is shown below:
```yaml
apis:
@@ -84,34 +92,44 @@ apis:
If you try to execute the `lint` command without apis when your project doesn't have any configuration files, the `lint` command displays an error.
{% /admonition %}
### Custom configuration file
### Use custom configuration file
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.
`redocly lint --config=./another/directory/config.yaml`
```bash
redocly lint --config=./another/directory/config.yaml
```
### Extend configuration
The `--extends` option allows you to extend the existing configuration. This option accepts one of the following values: `minimal`, `recommended`, `recommended-strict` or `all`. Each of the values is a base set of rules that the lint command uses. You can further modify this set in cases when you want to have your own set of rules based on the existing one, including particular rules that cover your specific needs.
The `--extends` option allows you to extend the existing configuration. This option accepts one of the following values: `minimal`, `recommended`, or `recommended-strict`. Each of the values is a base set of rules that the `lint` command uses. You can further modify this set in cases when you want to have your own set of rules based on the existing one, including particular rules that cover your specific needs. For more details, see [rulesets](../rules.md).
```bash
redocly lint --extends=recommended-strict
```
{% admonition type="warning" name="Important" %}
When you run the `lint` command without a configuration file, it uses the `extends: [recommended]` by default.
However, if you have a configuration file, but it doesn't include any rules or extends configuration, the `lint` command shows an error.
However, if you have a configuration file, but it doesn't include any rules or extends configuration, the `lint` command displays an error.
{% /admonition %}
### Format lint output
### Specify output format
The standard codeframe output format works well in most situations, but `redocly` can also produce output to integrate with other tools.
The standard `codeframe` output format works well in most situations, but `redocly` can also produce output to integrate with other tools.
{% admonition type="warning" name="Lint one API at a time" %}
Some formats, such as CheckStyle or JSON, don't work well when mulitple APIs are linted in a single command. Try linting each API separately when you pass the command output to another tool.
Some formats, such as `checkstyle` or `json`, don't work well when multiple APIs are linted in a single command. Try linting each API separately when you pass the command output to another tool.
{% /admonition %}
#### Codeframe (default)
The command `redocly lint --format=codeframe` lints the file and uses the default format of `codeframe`. It produces the same output as below if you omit the `--format` parameter.
```bash
redocly lint --format=codeframe
```
This command lints the file and uses the default output format of `codeframe`. It has the same behavior as omitting the `--format` parameter. Here's an output example:
<pre>
[1] museum-with-errors.yaml:19:7 at #/paths/~1museum-hours/get/operationIds
Property `operationIds` is not expected here.
@@ -125,7 +143,7 @@ Did you mean: operationId ?
21 | - Operations
Error was generated by the spec rule.
```
</pre>
Note that the problems are displayed in the following format: `file:line:column`. For example, `museum-with-errors.yaml:19:7`.
@@ -133,22 +151,30 @@ Depending on the terminal emulator you use, it may be possible to directly click
#### Stylish
The command `redocly lint --format=stylish` gives a more condensed output that is useful for summarizing the linting results, as seen below:
```bash
redocly lint --format=stylish
```
This command uses the `stylish` format to get a more condensed output that is useful for summarizing the linting results, as seen in the example below:
<pre>
museum-with-errors.yaml:
19:7 error spec Property `operationIds` is not expected here.
29:11 error spec Property `require` is not expected here.
16:5 warning operation-operationId Operation object should contain `operationId` field.
```
</pre>
In this format, `lint` shows the file name, line number, and column where the problem occurred. However, the output is compressed and omits other contexts and suggestions.
##### JSON
It can be useful to get the output in JSON format to be processed by other tools. Use a command like `redocly lint --format=json` to get the following output:
#### JSON
```bash
redocly lint --format=json
```
It can be useful to get the output in JSON format to be processed by other tools. Using this command gets the following example output:
<pre>
{
"totals": {
"errors": 2,
@@ -206,14 +232,17 @@ It can be useful to get the output in JSON format to be processed by other tools
}
]
}
```
</pre>
#### Checkstyle
The `lint` command also supports the [Checkstyle](https://checkstyle.org/) XML report format
Use a command like `redocly lint --format=checkstyle` to get this standard format output to use with your other tools.
```bash
redocly lint --format=checkstyle
```
The `lint` command also supports the [Checkstyle](https://checkstyle.org/) XML report format. Use this command to get the following standard format output to use with your other tools:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="4.3">
<file name="museum-with-errors.yaml">
@@ -230,14 +259,18 @@ omitted.
#### GitHub Actions
The `lint` command also comes with support for a [GitHub Actions](https://docs.github.com/en/actions) specific formatting.
Use `redocly lint --format=github-actions` to have any encountered problem annotated on the affected files.
```bash
redocly lint --format=github-actions
```
The `lint` command also comes with support for a [GitHub Actions](https://docs.github.com/en/actions) specific formatting.
Specify this output format to have any encountered problem annotated on the affected files.
<pre>
::error title=spec,file=museum-with-errors.yaml,line=19,endLine=19,col=7,endColumn=7::Property `operationIds` is not expected here.
::error title=spec,file=museum-with-errors.yaml,line=29,endLine=29,col=11,endColumn=11::Property `require` is not expected here.
::warning title=operation-operationId,file=museum-with-errors.yaml,line=16,endLine=16,col=5,endColumn=5::Operation object should contain `operationId` field.
```
</pre>
#### Markdown
@@ -246,7 +279,7 @@ This output format is useful if you want to report the outcomes to a document, o
Running the `lint` command with `--format=markdown` produces output like the following example:
```bash
<pre>
## Lint: ./museum-with-errors.yaml
| Severity | Location | Problem | Message |
@@ -256,22 +289,28 @@ Running the `lint` command with `--format=markdown` produces output like the fol
Validation failed
Errors: 2
```
</pre>
The output includes a formatted table, and links to any built-in rules that identified problems.
An example is shown in the following screenshot.
![Output of the lint command, Markdown rendered as HTML](./images/lint-markdown.png)
### <a id="max-problems"></a>Limit the problem count
### Limit the displayed problems count
With the `--max-problems` option, you can limit the number of problems displayed in the command output. If the number of detected problems exceeds the specified threshold, the remaining problems are hidden under the "spoiler message" that lets you know how many problems were hidden.
With the `--max-problems` option, you can limit the number of problems displayed in the command output. Here's an example command:
```bash
< ... 2 more problems hidden > increase with `--max-problems N`
redocly lint --max-problems=20
```
The default value is 100.
If the number of detected problems exceeds the specified threshold, the remaining problems are hidden under the "spoiler message" that lets you know how many problems were hidden.
<pre>
< ... 2 more problems hidden > increase with `--max-problems N`
</pre>
Note that the default value is `100`.
### Generate ignore file
@@ -279,21 +318,29 @@ With this option, you can generate the `.redocly.lint-ignore.yaml` file to suppr
This option is useful when you have an API design standard, but have some exceptions to the rule (for example, a legacy API operation). It allows for highly granular control.
`redocly lint museum-with-errors.yaml --generate-ignore-file` runs the lint command and adds all the errors to an ignore file.
```bash
Generated ignore file with 3 problems.
```
The errors in the ignore file `.redocly.lint-ignore.yaml` are ignored when the `lint` command is run.
{% admonition type="warning" %}
This command overwrites an existing ignore file.
{% /admonition %}
The following command runs `lint` and adds all the errors to an ignore file:
```bash
redocly lint museum-with-errors.yaml --generate-ignore-file
```
Here's the example output:
<pre>
Generated ignore file with 3 problems.
</pre>
The errors in the ignore file `.redocly.lint-ignore.yaml` are ignored when the `lint` command is run.
To generate an ignore file for multiple API descriptions, pass them as arguments:
`redocly lint v1.yaml v2.yaml --generate-ignore-file`
```bash
redocly lint v1.yaml v2.yaml --generate-ignore-file
```
Example of an ignore file:
@@ -314,14 +361,29 @@ The rule in the example is named `spec`, which indicates compliance with the Ope
You may want to skip specific preprocessors or rules upon running the command. Examples for each option are as follows:
- `redocly lint --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example`
{% tabs %}
{% tab label="Skip preprocessors" %}
- `redocly lint --skip-rule=no-sibling-refs --skip-rule=no-parent-tags`
```bash
redocly lint --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example
```
{% /tab %}
{% tab label="Skip rules" %}
```bash
redocly lint --skip-rule=no-sibling-refs --skip-rule=no-parent-tags
```
{% /tab %}
{% /tabs %}
{% admonition type="success" name="Tip" %}
To learn more about preprocessors, rules, and decorators, refer to the [custom plugins](../custom-plugins/index.md) page.
{% /admonition %}
### Lint config file
The `lint` command also validates the configuration file. You may want to set severity level by using the `--lint-config` option. This option accepts one of the following values: `warn`,`error`,`off`. Default value is `warn`.
```bash
redocly lint --lint-config=off
```

41
docs/commands/login.md
View File

@@ -4,16 +4,16 @@
Use the `login` command to authenticate to the API registry.
When you log in, the `preview-docs` command starts a preview server using Redocly API reference docs with all of the premium features. Users who are not logged in see a Redoc community edition version of their documentation.
When you log in, the [`preview-docs`](./preview-docs.md) command starts a preview server using [Redocly API reference docs](https://redocly.com/reference/) with all of the premium features. Users who are not logged in see a [Redoc community edition](https://redocly.com/redoc/) version of their documentation.
Also, you can access your members-only (private) API descriptions in the Redocly registry, and use the [`push`](./push.md) command.
After logging in, you can also access your members-only (private) API descriptions in the Redocly registry, and use the [`push`](./push.md) command.
If you're having issues with the `login` command, use the `--verbose` option to display a detailed error trace (if any).
## Usage
{% admonition type="warning" name="Note" %}
Go ahead and [generate a personal API key](https://redocly.com/docs/settings/personal-api-keys/); this key is needed to log in.
To log in, a personal API key is required. See [generate a personal API key](https://redocly.com/docs/settings/personal-api-keys/).
{% /admonition %}
```bash
@@ -24,37 +24,36 @@ redocly login --verbose
## Options
| Option | Type | Description |
| ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| --config | string | Specify path to the [config file](../configuration/index.md). |
| --help | boolean | Show help. |
| --region, -r | string | Specify which region to use when logging in. Supported values: `us`, `eu`. Read more about [configuring the region](../configuration/index.md). |
| --verbose | boolean | Include additional output. |
| --version | boolean | Show version number. |
| Option | Type | Description |
| ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| --config | string | Specify path to the [configuration file](../configuration/index.md). |
| --help | boolean | Show help. |
| --region, -r | string | Specify which region to use when logging in. Supported values: `us`, `eu`. The `eu` region is limited to enterprise customers. Default value is `us`. |
| --verbose | boolean | Display additional output. |
| --version | boolean | Show version number. |
## Examples
{% tabs %}
{% tab label="Successful login" %}
### View successful login message
```bash
A confirmation message is displayed with a successful login:
<pre>
redocly login
🔑 Copy your API key from https://app.redocly.com/profile and paste it below:
Logging in...
Authorization confirmed. ✅
```
</pre>
{% /tab %}
{% tab label="Failed login" %}
### View failed login message
```bash
An error message is displayed with a failed login:
<pre>
redocly login
🔑 Copy your API key from https://app.redocly.com/profile and paste it below:
Logging in...
Authorization failed. Please check if you entered a valid API key.
```
{% /tab %}
{% /tabs %}
</pre>

11
docs/commands/logout.md
View File

@@ -2,7 +2,8 @@
## Introduction
The `logout` command clears the API key from your device.
Use the `logout` command to clear the API key from your device.
You may want to `logout` if you are using a shared work computer or want to [`login`](./login.md) with another API key.
## Usage
@@ -21,7 +22,11 @@ redocly logout --version
## Examples
```bash
### View successful logout message
A confirmation message is displayed with a successful logout:
<pre>
redocly logout
Logged out from the Redocly account. ✋
```
</pre>

44
docs/commands/preview-docs.md
View File

@@ -2,7 +2,8 @@
## Introduction
With this command, you can generate documentation previews for API descriptions on your local machine.
With the `preview-docs` command, you can generate documentation previews for API descriptions on your local machine.
Use the previews to develop your API descriptions locally before deployment.
If you have a license key or API key configured, the output is a preview of the premium [Redocly API reference docs](https://redocly.com/reference/). Otherwise, it is a preview of [Redoc community edition](https://redocly.com/redoc/).
@@ -23,8 +24,8 @@ redocly preview-docs <api> --version
| Option | Type | Description |
| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api | string | Path to the API description filename or alias that you want to generate the preview for. Refer to [the api section](#api) for more options. |
| --config | string | Specify path to the [configuration file](#custom-configuration-file). |
| api | string | Path to the API description filename or alias that you want to generate the preview for. Refer to [the API section](#specify-api) for more details. |
| --config | string | Specify path to the [configuration file](#use-alternative-configuration-file). |
| --force, -f | boolean | Generate preview output even when errors occur. |
| --help | boolean | Show help. |
| --host, -h | string | The host where the documentation preview can be accessed. The default value is `127.0.0.1`. |
@@ -37,30 +38,22 @@ redocly preview-docs <api> --version
## Examples
### Api
### Specify API
The command behaves differently depending on how you pass the api to it, and whether the [configuration file](#custom-configuration-file) exists.
The `preview-docs` command behaves differently depending on how you pass the API to it, and whether the [configuration file](#use-alternative-configuration-file) exists.
#### Pass api directly
#### Pass an 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.
In this case, `preview-docs` previews the API description that was passed to the command. Any configuration file is ignored.
#### Pass api alias
#### Pass an API alias
Instead of a full path, you can use an API name from the `apis` section of your Redocly configuration file.
{% tabs %}
{% tab label="Command" %}
```bash
redocly preview-docs core@v1
```
{% /tab %}
{% tab label="Configuration file" %}
For example, with a `redocly.yaml` configuration file containing the following entry for `core@v1`:
```yaml
apis:
@@ -68,20 +61,23 @@ apis:
root: ./openapi/api-description.json
```
{% /tab %}
{% /tabs %}
You can generate a preview by giving the API alias name, as shown below:
In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `preview-docs` generates a preview of the `api-description.json` file. For this approach, the Redocly configuration file is mandatory.
```bash
redocly preview-docs core@v1
```
### Custom configuration file
In this case, after resolving the path behind the `core@v1` name, `preview-docs` generates a preview of the `api-description.json` file. For this approach, the Redocly configuration file is mandatory.
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.
### Use alternative configuration file
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 preview-docs --config=./another/directory/config.yaml
```
### Custom port for preview
### Use custom port for preview
By default, without using the `port` option, the preview starts on port `8080`, so you can access the docs at `http://localhost:8080`
@@ -105,7 +101,7 @@ redocly preview-docs -port 8888 openapi/openapi.yaml
Both commands start the preview on port `8888`, so you can access the docs at `http://localhost:8888`.
### Custom host for preview
### Use custom host for preview
By default, without using the `host` option, the preview starts on host `127.0.0.1`, so you can access the docs at `http://127.0.0.1:8080` or `http://localhost:8080`.

38
docs/commands/preview.md
View File

@@ -2,10 +2,10 @@
## Introduction
The `preview` command starts a local preview server for a Redocly project. Use the preview to develop your project locally before deployment.
The `preview` command starts a local preview server for a Redocly project. Use the preview server to develop your project locally before deployment.
{% admonition type="warning" name="Pre-release" %}
This command is for our pre-release products, currently open for early access to a small number of users. Announcements regarding the release are made through our [mailing list](https://redocly.com/product-updates/).
This command is for our pre-release products, currently open for early access to a small number of users. Announcements about the release are made through our [mailing list](https://redocly.com/product-updates/).
{% /admonition %}
## Usage
@@ -19,20 +19,20 @@ redocly preview --product=reef --plan=pro --source-dir=./my-docs-project --port=
## Options
| Option | Type | Description |
| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| --help | boolean | Shows help. |
| --plan | string | Product plan to use in preview. <br/> **Possible values:** `pro`, `enterprise`. The default value is `enterprise`. |
| --product | string | Name of a project to preview the product with. <br/> **Possible values:** `redoc`, `revel`, `reef`, `realm`, `redoc-revel`, `redoc-reef`, `revel-reef`. The default value is autodetected from the project's `package.json` or `realm` is used. |
| --source-dir, -d | string | Path to the project directory. The default value is `.` (current directory). |
| --port | number | The port to run the preview server on. The default value is `4000`. |
| --version | boolean | Shows version number. |
| Option | Type | Description |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| --help | boolean | Show help. |
| --plan | string | Product plan to use in preview. <br/> **Possible values:** `pro`, `enterprise`. The default value is `enterprise`. For more details, see [plans](https://redocly.com/pricing/). |
| --product | string | Name of a product to preview the project with. <br/> **Possible values:** `redoc`, `revel`, `reef`, `realm`, `redoc-revel`, `redoc-reef`, `revel-reef`. <br/> `redoc` is the flagship product for generating API documentation from OpenAPI specifications. <br/> `revel` is a specialized product designed for external API applications. <br/> `reef` is a specialized product designed for internal API needs. <br/> `realm` is a balanced product combining `redoc`, `revel`, and `reef`. <br/> `redoc-revel` is a blended product combining `redoc` and `revel`. <br/> `redoc-reef` is a blended product combining `redoc` and `reef`. <br/> `revel-reef` is a blended product combining `revel` and `reef`. <br/> The default value is autodetected from the project's `package.json` or `realm` is used. |
| --source-dir, -d | string | Path to the project directory. The default value is `.` (current directory). |
| --port | number | The port to run the preview server on. The default value is `4000`. |
| --version | boolean | Show version number. |
## Examples
### Select a product for preview
Specify the product package to use by setting a `--product` argument.
Specify the product package to use by setting the `--product` option.
If this setting is not supplied, the preview command tries to guess which package to use from the project's `package.json` or use `realm` by default.
```bash
@@ -41,8 +41,8 @@ redocly preview --product=revel
### Select a plan for preview
Previews are run in enterprise plan mode by default. This mode makes all of the enterprise features available.
Switch the preview to pro plan mode by setting `--plan` to `pro`.
By default, previews are run in enterprise plan mode. This mode makes all of the enterprise features available.
Switch the preview to pro plan mode by setting the `--plan` option to `pro`:
```bash
redocly preview --plan=pro
@@ -50,18 +50,20 @@ redocly preview --plan=pro
### Specify project directory
The preview command uses the current directory by default. To specify another directory, provide a path to it relative to the current directory:
By default, the preview command uses the current directory. To specify another directory, provide a path relative to the current directory using the `--source-dir` option:
```bash
redocly preview --source-dir=./path/to/my/docs/
```
### Custom port for preview
### Use custom port for preview
The preview starts on port `4000` by default, so you can access the docs at `http://localhost:4000` or `http://127.0.0.1:4000`.
By default, the preview starts on port `4000`, so you can access the docs at `http://localhost:4000` or `http://127.0.0.1:4000`.
To specify a custom port for the preview, pass the desired value using a `port` option:
To specify a custom port for the preview, pass the desired value using the `port` option:
```bash
redocly preview --port=8080
redocly preview --port=8888
```
This command starts the preview on port 8888, so you can access the docs at `http://localhost:8888` or `http://127.0.0.1:8888`.

127
docs/commands/push.md
View File

@@ -8,14 +8,14 @@ The Redocly CLI `push` command helps you automate API description updates withou
This allows you to:
- Benefit from using Redocly Workflows to preview documentation and portal builds.
- Use Redocly Workflows to preview documentation and portal builds.
- Manage versions in the API registry.
Apart from uploading your API description file, the `push` command can automatically upload other files if they are detected or referenced in the API description:
Apart from uploading your API description file, the `push` command can automatically upload other files that are detected or referenced in the API description:
- the [Redocly configuration file](../configuration/index.md) and any configuration files referenced in the `extends` list.
- the `package.json` file (if it exists) from the folder where you're executing the `push` command. Redocly Workflows uses the `@redocly/cli` version specified in `package.json`.
- the HTML template and the full contents of the folder specified as the `theme.openapi.htmlTemplate` parameter in the Redocly configuration file.
- The [Redocly configuration file](../configuration/index.md) and any configuration files referenced in the `extends` list.
- The `package.json` file (if it exists) from the folder where you're executing the `push` command. Redocly Workflows uses the `@redocly/cli` version specified in `package.json`.
- The HTML template and the full contents of the folder specified as the `theme.openapi.htmlTemplate` parameter in the Redocly configuration file.
{% admonition type="attention" %}
If a plugin is referenced in the Redocly configuration file, the `push` command recursively scans the folder containing the plugin and uploads all `.js`, `.json`, `.mjs` and `.ts` files.
@@ -34,13 +34,13 @@ Only API descriptions with a CI source can be updated with the `push` command. A
Before using the `push` command, ensure the following prerequisites are met:
1. Active user account in a Redocly Workflows organization.
1. Active [personal API key or organization API key](https://redocly.com/docs/settings/personal-api-keys/).
2. Active [personal API key or organization API key](https://redocly.com/docs/settings/personal-api-keys/).
## Authentication
To authenticate to the API registry, you can use several approaches:
- use the [`login` command](login.md). In this case, the command is as follows:
- Use the `login` command. In this case, the command is as follows:
```bash
redocly login
@@ -49,7 +49,7 @@ To authenticate to the API registry, you can use several approaches:
Refer to the [`login` command documentation](login.md) for more details.
- set the `REDOCLY_AUTHORIZATION` environment variable to either your [personal API key](https://redocly.com/docs/settings/personal-api-keys/) or to an organization-wide API key (configurable by organization owners in **Redocly Workflows > Settings > API keys**). In this case, the command may look as follows:
- Set the `REDOCLY_AUTHORIZATION` environment variable to either your [personal API key](https://redocly.com/docs/settings/personal-api-keys/) or an organization-wide API key (configurable by organization owners in **Redocly Workflows > Settings > API keys**). In this case, the command may look as follows:
```bash
REDOCLY_AUTHORIZATION=yourPersonalApiKey redocly push ...
@@ -59,46 +59,46 @@ To authenticate to the API registry, you can use several approaches:
- [Travis CI documentation](https://docs.travis-ci.com/user/environment-variables/)
- [CircleCI documentation](https://circleci.com/docs/env-vars/)
- [GitHub Actions documentation](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
- [GitHub Actions documentation](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions)
- [Jenkins documentation](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#handling-credentials)
## Usage
```bash
redocly push [api] [--destination] [--organization]
redocly push
redocly push [api] [--destination] [--organization]
redocly push [-u] [--job-id id] [--batch-size number] <path/to/api-description.yaml> [--destination] [--organization] [--branch]
```
## Options
| Option | Type | Description |
| ---------------- | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api | string | The API description that you want to push to the Redocly API registry. Provide it as a path to the root API description file (or as an alias). See [Set options explicitly](#set-options-explicitly) for more information. |
| --batch-size | number | Number of CI pushes expected within one batch. See [the Batch Size section](#batch-size) for more information. |
| --branch, -b | string | The branch where your API description is pushed or upserted. Default value is `main`. |
| --destination | string | The location in the API registry where you want to push or upsert your API description. Provide it in the following format: `api-name@api-version`. |
| --files | [string] | List of other folders and files to upload. See [the Files section](#files) for more information. |
| --help | boolean | Help output for the command. |
| --job-id | string | The ID of the CI job that the current push is associated with. See [the Job ID section](#job-id) for more information. |
| --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
| --organization | string | ID of organization that the API description is being pushed to. Overrides the one defined in the config file. |
| --public | boolean | Make API descriptions publicly accessible from the API Registry. Read more about [using the public option](#public). |
| --region,-r | string | Which region to use when logging in. Supported values: `us`, `eu`. The `eu` region is limited to enterprise customers. Default value is `us`. Alternatively, set an environment variable `REDOCLY_DOMAIN` with the value of the appropriate Redocly API. |
| --skip-decorator | [string] | Ignore one or more decorators. See the [Skip decorator section](#skip-decorator) for usage examples. |
| --upsert, -u | boolean | Create a new version of an API when pushing to the API registry if the version doesn't exist. See [the Upsert an API with push section](#upsert-an-api-with-push) for more information. |
| --version | boolean | Show version number. |
| Option | Type | Description |
| ---------------- | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api | string | The API description that you want to push to the Redocly API registry. Provide it as a path to the root API description file (or as an alias). See [set options explicitly](#set-options-explicitly) for more information. |
| --batch-size | number | Number of CI pushes expected within one batch. Must be used only in combination with the `--job-id` option. Must be an integer bigger than 1. See [the pushes per batch section](#determine-how-many-pushes-are-performed-per-batch) for more information. |
| --branch, -b | string | The branch where your API description is pushed or upserted. Default value is `main`. |
| --destination | string | The location in the API registry where you want to push or upsert your API description. Provide it in the following format: `api-name@api-version`. |
| --files | [string] | List of other folders and files to upload. See [the files section](#upload-other-folders-and-files) for more information. |
| --help | boolean | Show help. |
| --job-id | string | The ID of the CI job that the current push is associated with. Must be used only in combination with the `--batch-size` option. See [the job ID section](#specify-job-id) for more information. |
| --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
| --organization | string | ID of organization that the API description is being pushed to. Overrides the one defined in the configuration file. |
| --public | boolean | Make API descriptions publicly accessible from the API Registry. Read more about [using the public option](#make-api-descriptions-publicly-accessible). |
| --region,-r | string | Specify which region to use when logging in. Supported values: `us`, `eu`. The `eu` region is limited to enterprise customers. Default value is `us`. Alternatively, set an environment variable `REDOCLY_DOMAIN` with the value of the appropriate Redocly API. |
| --skip-decorator | [string] | Ignore one or more decorators. See [the skip decorator section](#skip-decorator) for usage examples. |
| --upsert, -u | boolean | Create a new version of an API when pushing to the API registry if the version doesn't exist. See [the upsert an API with push section](#upsert-an-api-with-push) for more information. |
| --version | boolean | Show version number. |
## Examples
The command behaves differently depending on the options you pass to it and whether the configuration file exists in your working directory.
The command behaves differently depending on the options you pass to it, and whether the configuration file exists in your working directory.
You can choose any of the following approaches:
- [Specify all options explicitly in the command](#set-options-explicitly)
- [Set options in the Redocly configuration file](#set-options-in-the-configuration-file)
### Destination
### Specify destination
To properly push your API description to the Redocly API registry, you need the following information:
@@ -107,8 +107,10 @@ To properly push your API description to the Redocly API registry, you need the
#### Organization ID
The `push` command uses the following order of precedence: first, it takes the organization ID from command-line arguments (if provided).
If the organization ID is not provided explicitly, it takes it from the configuration file.
The `push` command uses the following order of precedence:
1. First, it takes the organization ID from command-line arguments (if provided).
1. If the organization ID is not provided explicitly, it takes it from the configuration file.
To find your organization ID required for the command:
@@ -119,12 +121,14 @@ To find your organization ID required for the command:
For example, if the URL is `app.redocly.com/org/test_docs`, the organization ID is `test_docs`. When using the `push` command, you would provide this ID as `--organization=test_docs`.
{% admonition type="warning" name="Note" %}
The organization ID can differ from the organization name. Owners can change the organization name at any time in the Workflows **Settings** page, but the organization ID cannot be changed.
{% /admonition %}
Note that the organization ID can differ from the organization name. Owners can change the organization name at any time in the Workflows **Settings** page, but the organization ID cannot be changed.
#### API name and version
{% admonition type="attention" %}
The name and version of your API should contain only supported characters (`a-z`, `A-Z`, `0-9`, `-`, `.`). Using a restricted character results in an error, and your API doesn't get created.
{% /admonition %}
To find your API name required for the command:
1. Log into Workflows.
@@ -132,10 +136,6 @@ To find your API name required for the command:
1. Check the list of APIs displayed on this page.
1. Inspect the title of each list item to the left of the **New version** and **Edit API** action buttons. This title is an API name.
{% admonition type="attention" %}
The name of your API should contain only supported characters (`a-z`, `A-Z`, `0-9`, `-`, `.`). Using a restricted character results in an error, and your API doesn't get created.
{% /admonition %}
To find your API version required for the command:
1. Log into Workflows.
@@ -143,15 +143,11 @@ To find your API version required for the command:
1. Check the list of APIs displayed on this page.
1. The version is displayed in the title after the `@` in format `<name> @ <version>`.
When using the `push` command, you would provide the API name and version separated with the "at" symbol (`@`). For example: `--destination=petstore-api@v1`.
{% admonition type="attention" %}
The version of your API should contain only supported characters (`a-z`, `A-Z`, `0-9`, `-`, `.`). Using a restricted character results in an error, and your API doesn't get created.
{% /admonition %}
When using the `push` command, you would provide the API name and version in the format `api-name@api-version`. For example: `--destination=petstore-api@v1`.
### Set options explicitly
Provide the `api` as a path to the root API description file, and specify the organization ID, API name and version.
Provide the `api` as a path to the root API description file, and specify the organization ID, API name, and API version.
```bash
redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org
@@ -169,7 +165,7 @@ redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=
Depending on the contents of your Redocly configuration file, you can use simplified `push` syntax instead of providing the full path to the API description file.
**Example configuration file**
Here's an example configuration file:
```yaml
organization: organization-id
@@ -180,20 +176,30 @@ apis:
root: openapi/openapi.yaml
```
With a configuration file like this, you can use any of the following commands:
With a configuration file like this, you can use any of the following approaches:
1. `redocly push`
- Push all configured APIs
Push every API listed in the `apis` section of the configuration file.
You must specify your Workflows organization ID in the configuration file for this approach to work.
APIs without an explicitly defined version are automatically pushed to `@latest`.
```bash
redocly push
```
2. `redocly push --destination=api-name@api-version`
Push every API listed in the `apis` section of the configuration file. You must specify your Workflows organization ID in the configuration file for this approach to work. APIs without an explicitly defined version are automatically pushed to `@latest`.
- Push specified API and version
```bash
redocly push --destination=api-name@api-version
```
Push the specified API and version from the `apis` section of the configuration file.
You must specify your organization ID in the configuration file for this approach to work.
3. `redocly push --destination=api-name@api-version --organization=organization-id`
- Push specified API and version with organization ID
```bash
redocly push --destination=api-name@api-version --organization=organization-id
```
Push the specified API and version from the `apis` section of the configuration file to the Workflows organization matching the provided organization ID.
In this case, you don't have to specify the organization ID in the configuration file.
@@ -224,7 +230,8 @@ redocly push -u
{% /tab %}
{% /tabs %}
To upsert the API description to a particular branch, specify the branch name with `--branch` or `-b`.
To upsert the API description to a particular branch, specify the branch name with the `--branch` or `-b` option.
{% tabs %}
{% tab label="Set options explicitly" %}
@@ -242,18 +249,18 @@ redocly push -u test-api@v1 -b develop
{% /tab %}
{% /tabs %}
### Job ID
### Specify job ID
The `--job-id` option can be used by Redocly Workflows to associate multiple pushes with a single CI job.
Below are possible use cases for the `--job-id` option:
- CI/CD systems: group pushes from a single CI job together so that each push does not trigger separate reference docs/portals rebuild.
- External systems: a parameter that can be used in reports, metrics, analytics to refer to a specific application service state.
- External systems: a parameter that can be used in reports, metrics, or analytics to refer to a specific application service state.
Must be used only in combination with the `--batch-size` option.
### Batch Size
### Determine how many pushes are performed per batch
The `--batch-size` option can be used by Redocly Workflows to understand how many pushes in total are performed within one batch to properly handle parallel pushes.
@@ -279,7 +286,7 @@ redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=
{% /tab %}
{% /tabs %}
### Public
### Make API descriptions publicly accessible
The `--public` option allows you to upload your API description and make it publicly accessible from the API Registry. By default, API descriptions uploaded with the `push` command are not available to the public.
For more information on how to configure access to your APIs, check the [registry access](https://redocly.com/docs/api-registry/settings/manage-access/#set-up-access-to-api-registry) section.
@@ -288,7 +295,7 @@ 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
### Upload other folders and files
The `--files` option allows you to upload other folders and files.
@@ -296,7 +303,7 @@ The `--files` option allows you to upload other folders and files.
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 the `redocly.yaml` configuration file:
```yaml
apis:
@@ -308,7 +315,7 @@ files:
- ./file.md
```
**`--files` has higher priority than `redocly.yaml`**
Note that the `--files` option has higher priority than the `redocly.yaml` configuration file.
### Set up CI from Redocly Workflows
@@ -316,4 +323,4 @@ The Redocly Workflows interface can help you get started with the `push` command
1. In **API registry**, select **Add API**.
1. In the **Definition name** step, provide a name for your new API description.
1. In the **Choose source** step, select **Upload from CI/CD**. This generates syntax for the `push` command that you can copy and use to upload a new API description file. Or use the `redocly push -u` command directly from the command-line interface.
1. In the **Choose source** step, select **Upload from CI/CD**. This generates syntax for the `push` command that you can copy and use to upload a new API description file. Or use the [`redocly push -u` command](#upsert-an-api-with-push) directly from the command-line interface.

27
docs/commands/split.md
View File

@@ -2,9 +2,9 @@
## Introduction
The `split` command takes an API description file and creates a [multi-file structure](https://redocly.com/docs/resources/multi-file-definitions/) out of it by extracting referenced parts into standalone, separate files. The advantage of this approach is making smaller files that are easier to manage and a structure that makes reviewing simpler.
The `split` command takes an API description file and creates a [multi-file structure](https://redocly.com/docs/resources/multi-file-definitions/) out of it by extracting referenced parts into standalone, separate files. Code samples, components, and paths are split from the root API description into separate files and folders. The structure of the unbundled directory corresponds to the structure created by our [openapi-starter](https://github.com/Redocly/openapi-starter) tool. The advantage of this approach is making smaller files that are easier to manage and a structure that makes reviewing simpler.
Use `bundle` and supply the main file as the entrypoint to get your OpenAPI description in one file. Many OpenAPI tools prefer a single file, but `split` and `bundle` allow you to manage your files easily for development, and then prepare a single file for other tools to consume.
Use the [`bundle`](./bundle.md) command and supply the main file as the entrypoint to get your OpenAPI description in one file. Many OpenAPI tools prefer a single file, but `split` and `bundle` allow you to manage your files easily for development, and then prepare a single file for other tools to consume.
{% admonition type="warning" name="OpenAPI 3.x only" %}
The `split` command doesn't support OpenAPI 2.0 descriptions.
@@ -23,33 +23,28 @@ redocly split --version
| Option | Type | Description |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api | string | **REQUIRED.** Path to the API description file that you want to split into a multi-file structure. |
| --config | string | Specify path to the [config file](../configuration/index.md). |
| --config | string | Specify path to the [configuration file](../configuration/index.md). |
| --help | boolean | Show help. |
| --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
| --outDir | string | **REQUIRED.** Path to the directory where you want to save split files. If the specified directory doesn't exist, it is created automatically. |
| --outDir | string | **REQUIRED.** Path to the directory where you want to save the split files. If the specified directory doesn't exist, it is created automatically. |
| --separator | string | File path separator used while splitting. The default value is `_`. This controls the file names generated in the `paths` folder (e.g. `/users/create` path becomes `user_create.yaml`). |
| --version | boolean | Show version number. |
## Example
## Examples
{% tabs %}
{% tab label="Command" %}
### View successful split message
This `split` command "unbundles" the specified API description, as defined in `pet.yaml`, into the `openapi` output directory:
```bash
redocly split pet.yaml --outDir=openapi
```
{% /tab %}
{% tab label="Output" %}
A confirmation message is displayed with a successful split:
```bash
<pre>
Document: pet.yaml is successfully split
and all related files are saved to the directory: openapi
pet.yaml: split processed in 33ms
```
{% /tab %}
{% /tabs %}
In the `openapi` directory, the `split` command "unbundles" the specified API description. Code samples, components, and paths are split from the root API description into separate files and folders. The structure of the unbundled directory corresponds to the structure created by our [openapi-starter](https://github.com/Redocly/openapi-starter) tool.
</pre>

84
docs/commands/stats.md
View File

@@ -26,22 +26,22 @@ redocly stats --version
## Options
| Option | Type | Description |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| api | string | **REQUIRED.** Path to the API description file that you want to split into a multi-file structure. |
| --config | string | Specify path to the [configuration file](#custom-configuration-file). |
| --format | string | Format for the output.<br />**Possible values:** `stylish`, `json`, `markdown`. |
| --help | boolean | Show help. |
| --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
| --version | boolean | Show version number. |
| Option | Type | Description |
| ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api | string | **REQUIRED.** Path to the API description filename or alias that you want to generate the statistics for. Refer to [the API section](#specify-api) for more details. |
| --config | string | Specify path to the [configuration file](#use-alternative-configuration-file). |
| --format | string | Format for the output.<br />**Possible values:** `stylish`, `json`, `markdown`. Default value is `stylish`. |
| --help | boolean | Show help. |
| --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
| --version | boolean | Show version number. |
## Examples
### API
### Specify API
The `stats` command behaves differently depending on how you pass the API to it and whether the [configuration file](#custom-configuration-file) exists.
The `stats` command behaves differently depending on how you pass the API to it, and whether the [configuration file](#use-alternative-configuration-file) exists.
#### Pass an OpenAPI file
#### Pass an API directly
You can use the `stats` command with an OpenAPI description directly, with a command like the following:
@@ -49,12 +49,12 @@ You can use the `stats` command with an OpenAPI description directly, with a com
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.
#### Use an API alias in the configuration file
#### Pass an API alias
Instead of full paths, you can use API names from the `apis` section of your Redocly configuration file.
With a `redocly.yaml` file containing the following entry for `core@v1`:
Instead of a full path, you can use an API name from the `apis` section of your Redocly configuration file.
For example, with a `redocly.yaml` configuration file containing the following entry for `core@v1`:
```yaml
apis:
@@ -62,15 +62,15 @@ apis:
root: ./openapi/api-description.json
```
You can obtain the stats by giving the API alias name, as shown below:
You can obtain the statistics by giving the API alias name, as shown below:
```bash
redocly stats core@v1
```
In this case, after resolving the path behind the `core@v1` name, `stats` displays statistics for the `openapi/api-description.json` file.
In this case, after resolving the path behind the `core@v1` name, `stats` displays statistics for the `openapi/api-description.json` file. For this approach, the Redocly configuration file is mandatory.
### Custom configuration file
### Use alternative configuration file
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.
@@ -78,14 +78,14 @@ By default, the CLI tool looks for the [Redocly configuration file](../configura
redocly stats --config=./another/directory/config.yaml
```
### Format
### Specify output format
#### Stylish (default)
#### Specify the stylish (default) output format
The default output format for `stats` is called "stylish".
It outputs a nice format for your terminal, as shown in the following example:
```bash
<pre>
Document: museum.yaml stats:
🚗 References: 35
@@ -98,17 +98,16 @@ Document: museum.yaml stats:
🔖 Tags: 3
museum.yaml: stats processed in 4ms
```
</pre>
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
#### Specify the JSON output format
Add `--format=json` to get a machine-readable output format.
The JSON format outout is great when you want to grab the stats data to use elsewhere.
An example of the format is shown in the following example:
Use `--format=json` to get a machine-readable output format.
The JSON format output is shown in the following example:
```json
<pre>
{
"refs": {
"metric": "🚗 References",
@@ -143,16 +142,18 @@ An example of the format is shown in the following example:
"total": 3
}
}
```
</pre>
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
#### Specify the Markdown output format
Add `--format=markdown` and the command returns output that you can use in Markdown files or other Markdown-friendly applications.
It uses a table format; there are examples of the source and the formatted output below:
Use `--format=markdown` to return output that you can use in Markdown files or other Markdown-friendly applications.
A table format is used.
```markdown
The following is an example source output:
<pre>
| Feature | Count |
| --- | --- |
| 🚗 References | 35 |
@@ -163,7 +164,10 @@ It uses a table format; there are examples of the source and the formatted outpu
| 🔀 Path Items | 5 |
| 👷 Operations | 8 |
| 🔖 Tags | 3 |
```
</pre>
Here's the rendered example source output:
| Feature | Count |
| --------------------- | ----- |
@@ -176,9 +180,9 @@ It uses a table format; there are examples of the source and the formatted outpu
| 👷 Operations | 8 |
| 🔖 Tags | 3 |
The Markdown format is very useful for situations where a printable summary is useful.
A good example is using it with regular update reports, or as a human-readable output from your CI system.
The following example shows how to use the `stats` command in a GitHub action to make a nice [GitHub summary](https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/):
The Markdown format is suitable when a printable summary is needed, such as for regularly updated reports or human-readable output from your CI system.
The following example shows how to use the `stats` command in a GitHub action to make a [GitHub summary](https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/):
```yaml
name: Get API stats
@@ -199,7 +203,7 @@ jobs:
run: redocly stats --format=markdown museum.yaml >> $GITHUB_STEP_SUMMARY 2>&1
```
This GitHub action uses the output of the `stats` command in Markdown format as the value for `$GITHUB_STEP_SUMMARY`.
When the job is complete, it adds your API stats to the summary page, as shown in the following screenshot:
This GitHub action uses the output of the `stats` command in Markdown format as the input value for `$GITHUB_STEP_SUMMARY`.
When the job is complete, your API stats are added to the summary page, as shown in the following screenshot:
![GitHub job summary showing API stats](./images/stats-github-job-summary.png)