diff --git a/docs/commands/build-docs.md b/docs/commands/build-docs.md index 5426d707e3..00c5f0f683 100644 --- a/docs/commands/build-docs.md +++ b/docs/commands/build-docs.md @@ -16,18 +16,19 @@ redocly build-docs -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. | -| --output, -o | string | Sets the path and name of the output file. The default value is `redoc-static.html`. | -| --title | string | Sets the page title. | -| --disableGoogleFont | boolean | Disables Google fonts. The default value is `false`. | -| --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/). | -| --config | string | Specifies path to the [configuration file](#custom-configuration-file). | -| --help | boolean | Shows help. | -| --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 examples](#api-examples) for more information. | +| --output, -o | string | Sets the path and name of the output file. The default value is `redoc-static.html`. | +| --title | string | Sets the page title. | +| --disableGoogleFont | boolean | Disables Google fonts. The default value is `false`. | +| --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/). | +| --config | string | Specifies path to the [configuration file](#custom-configuration-file). | +| --help | boolean | Shows help. | +| --version | boolean | Shows version number. | +| --lint-config | string | Specify the severity level for the configuration file.
**Possible values:** `warn`, `error`, `off`. Default value is `warn`. | ## Examples diff --git a/docs/commands/bundle.md b/docs/commands/bundle.md index 622b1244fb..5502580536 100644 --- a/docs/commands/bundle.md +++ b/docs/commands/bundle.md @@ -22,7 +22,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. | +| 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). | | --dereferenced, -d | boolean | Generate fully dereferenced bundle. | | --ext | string | Specify bundled file extension. Possible values are `json`, `yaml`, or `yml`. Default value is `yaml`. | @@ -31,7 +31,7 @@ redocly bundle --version | --format | string | Format for the output. Possible values are `codeframe`, `stylish`, `json`, or `checkstyle`. Default value is `codeframe`. | | --help | boolean | Show help. | | --keep-url-references, -k | boolean | Keep absolute url references. | -| --lint | boolean | Lint API description files. Default value is `false`. | +| --lint | boolean | Lint API description files. Default value is `false`. | | --max-problems | integer | Truncate output to display the specified maximum number of problems. Default value is `100`. | | --metafile | string | Path for the bundle metadata file. | | --output, -o | string | Name or folder for the bundle file. If you don't specify the file extension, `.yaml` is used by default. If the specified folder doesn't exist, it's created automatically. **If the file specified as the bundler's output already exists, it's overwritten.** | @@ -40,6 +40,7 @@ redocly bundle --version | --skip-preprocessor | [string] | Ignore certain preprocessors. See the [Skip preprocessor, rule, or decorator section](#skip-preprocessor-rule-or-decorator). | | --skip-rule | [string] | Ignore certain rules. See the [Skip preprocessor, rule, or decorator section](#skip-preprocessor-rule-or-decorator). | | --version | boolean | Show version number. | +| --lint-config | string | Specify the severity level for the configuration file.
**Possible values:** `warn`, `error`, `off`. Default value is `warn`. | ## Examples @@ -111,11 +112,14 @@ The compressed output omits other contexts and suggestions. {% tabs %} {% tab label="Command" %} + ```bash redocly bundle pet.yaml store.yaml -o ./bundled --format=json ``` + {% /tab %} {% tab label="Output" %} + ```bash bundling pet.yaml... { @@ -138,19 +142,24 @@ bundling store.yaml... "problems": [] }📦 Created a bundle for store.yaml at bundled/store.yaml 15ms. ``` + {% /tab %} {% /tabs %} In this format, `bundle` shows the result of bundling (including the number of errors and warnings and their descriptions) in JSON-like output. #### Checkstyle + {% tabs %} {% tab label="Command" %} + ```bash redocly bundle pet.yaml -o ./bundled --lint --format=checkstyle ``` + {% /tab %} {% tab label="Output" %} + ```bash bundling pet.yaml... @@ -160,6 +169,7 @@ bundling pet.yaml... 📦 Created a bundle for pet.yaml at bundled/pet.yaml 35ms. ``` + {% /tab %} {% /tabs %} In this format, `bundle` uses the [Checkstyle](https://checkstyle.org/) XML report format. @@ -172,19 +182,25 @@ All other information is omitted. You may want to skip specific preprocessors, rules, or decorators upon running the command. {% tabs %} {% tab label="Skip preprocessors" %} + ```bash redocly bundle --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example ``` + {% /tab %} {% tab label="Skip rules" %} + ```bash redocly bundle --skip-rule=no-sibling-refs --skip-rule=no-parent-tags ``` + {% /tab %} {% tab label="Skip decorators" %} + ```bash redocly bundle --skip-decorator=generate-code-samples --skip-decorator=remove-internal-operations ``` + {% /tab %} {% /tabs %} {% admonition type="success" name="Tip" %} diff --git a/docs/commands/join.md b/docs/commands/join.md index 63b08d1122..305eb4a824 100644 --- a/docs/commands/join.md +++ b/docs/commands/join.md @@ -49,22 +49,28 @@ redocly join --version | --version | boolean | Show version number. | | --output, -o | string | Name for the joined output file. Defaults to `openapi.yaml`. **If the file already exists, it's overwritten.** | | --config | string | Specify path to the [config file](../configuration/index.md). | +| --lint-config | string | Specify the severity level for the configuration file.
**Possible values:** `warn`, `error`, `off`. Default value is `warn`. | ## Examples ### Array of paths + {% tabs %} {% tab label="Command" %} + ```bash redocly join first-api.yaml second-api.json ``` + {% /tab %} {% tab label="Output" %} + ```bash redocly join first-api.yaml second-api.json openapi.yaml: join processed in 56ms ``` + {% /tab %} {% /tabs %} The command creates the output `openapi.yaml` file in the working directory. @@ -140,13 +146,17 @@ If any of the input files contain the `tags` object, tags in the output file are The output file preserves the original tag names as the value of the `x-displayName` property for each tag. #### Usage + {% tabs %} {% tab label="Command" %} + ```bash redocly join first-api.yaml second-api.json --prefix-tags-with-info-prop title ``` + {% /tab %} {% tab label="Output file example" %} + ```yaml - name: First Document title_endpoints description: endpoints tag description @@ -156,8 +166,10 @@ redocly join first-api.yaml second-api.json --prefix-tags-with-info-prop title description: pets tag description x-displayName: pets ``` + {% /tab %} {% /tabs %} + ### 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. @@ -165,13 +177,17 @@ If any of the input files contain the `tags` object, tags in the output file are The output file preserves the original tag names as the value of the `x-displayName` property for each tag. #### Usage + {% tabs %} {% tab label="Command" %} + ```bash redocly join first-api.yaml second-api.json --prefix-tags-with-filename true ``` + {% /tab %} {% tab label="Output file example" %} + ```yaml - name: first-api_endpoints description: endpoints tag description @@ -181,8 +197,10 @@ redocly join first-api.yaml second-api.json --prefix-tags-with-filename true description: pets tag description x-displayName: pets ``` + {% /tab %} {% /tabs %} + ### without-x-tag-groups 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. @@ -206,13 +224,17 @@ openapi.yaml: join processed in 69ms 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 + {% tabs %} {% tab label="Command" %} + ```bash redocly join first-api.yaml second-api.json --prefix-components-with-info-prop version ``` + {% /tab %} {% tab label="Output file example" %} + ```yaml components: schemas: @@ -246,8 +268,10 @@ components: type: integer format: int64 ``` + {% /tab %} {% /tabs %} + ### Custom output file By default, the CLI tool writes the joined file as `openapi.yaml` in the current working directory. Use the optional `--output` argument to provide an alternative output file path. diff --git a/docs/commands/preview-docs.md b/docs/commands/preview-docs.md index df8fe6b9b0..04eb13a130 100644 --- a/docs/commands/preview-docs.md +++ b/docs/commands/preview-docs.md @@ -23,7 +23,7 @@ redocly preview-docs --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. | +| 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). | | --force, -f | boolean | Generate preview output even when errors occur. | | --help | boolean | Show help. | @@ -33,6 +33,7 @@ redocly preview-docs --version | --skip-preprocessor | [string] | Ignore [certain preprocessors](#skip-preprocessor-or-decorator). | | --use-community-edition | boolean | Use Redoc Community Edition for docs preview. | | --version | boolean | Show version number. | +| --lint-config | string | Specify the severity level for the configuration file.
**Possible values:** `warn`, `error`, `off`. Default value is `warn`. | ## Examples @@ -53,16 +54,20 @@ In this case, `preview-docs` previews the API description that was passed to the 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" %} + ```yaml apis: core@v1: root: ./openapi/api-description.json ``` + {% /tab %} {% /tabs %} @@ -83,14 +88,18 @@ By default, without using the `port` option, the preview starts on port `8080`, To specify a custom port for the preview, pass the desired value using either short or long option format: {% tabs %} {% tab label="Short format" %} + ```bash redocly preview-docs -p 8888 openapi/openapi.yaml ``` + {% /tab %} {% tab label="Long format" %} + ```bash redocly preview-docs -port 8888 openapi/openapi.yaml ``` + {% /tab %} {% /tabs %} @@ -103,14 +112,18 @@ By default, without using the `host` option, the preview starts on host `127.0.0 To specify a custom host for the preview, pass the desired value using either short or long option format: {% tabs %} {% tab label="Short format" %} + ```bash redocly preview-docs -h 0.0.0.0 openapi/openapi.yaml ``` + {% /tab %} {% tab label="Long format" %} + ```bash redocly preview-docs --host 0.0.0.0 openapi/openapi.yaml ``` + {% /tab %} {% /tabs %} @@ -121,13 +134,17 @@ Both commands start the preview on host `0.0.0.0`, so you can access the docs at You may want to skip specific preprocessors, rules, or decorators upon running the command. {% tabs %} {% tab label="Skip preprocessors" %} + ```bash redocly preview-docs --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example ``` + {% /tab %} {% tab label="Skip decorators" %} + ```bash redocly preview-docs --skip-decorator=generate-code-samples --skip-decorator=remove-internal-operations ``` + {% /tab %} {% /tabs %} diff --git a/docs/commands/push.md b/docs/commands/push.md index 94b84e5095..d22f274ad5 100644 --- a/docs/commands/push.md +++ b/docs/commands/push.md @@ -72,21 +72,22 @@ redocly push [-u] [--job-id id] [--batch-size number] **Possible values:** `warn`, `error`, `off`. Default value is `warn`. | ## Examples @@ -202,34 +203,45 @@ In this case, you don't have to specify the organization ID in the configuration To upsert an API in the registry with the `push` command, use the `--upsert` or `-u` option. The upsert creates the destination if it doesn't exist, or updates it if it does. {% tabs %} {% tab label="Set options explicitly" %} + ```bash redocly push -u test-api-v1.yaml --destination=test-api@v1 --organization=redocly ``` + {% /tab %} {% tab label="Use config file" %} + ```bash redocly push -u --destination=test-api@v1 ``` + {% /tab %} {% tab label="Upsert all APIs from config file" %} + ```bash redocly push -u ``` + {% /tab %} {% /tabs %} To upsert the API description to a particular branch, specify the branch name with `--branch` or `-b`. {% tabs %} {% tab label="Set options explicitly" %} + ```bash redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org -b develop ``` + {% /tab %} {% tab label="Use config file" %} + ```bash Use config file redocly push -u test-api@v1 -b develop ``` + {% /tab %} {% /tabs %} + ### Job ID The `--job-id` option can be used by Redocly Workflows to associate multiple pushes with a single CI job. @@ -252,16 +264,21 @@ Must be used only in combination with the `--job-id` option. Must be an integer You may want to skip specific decorators upon running the command. {% tabs %} {% tab label="Skip a decorator" %} + ```bash redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org --skip-decorator=test/remove-internal-operations ``` + {% /tab %} {% tab label="Skip multiple decorators" %} + ```bash redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org --skip-decorator=test/remove-internal-operations --skip-decorator=test/remove-internal-schemas ``` + {% /tab %} {% /tabs %} + ### Public 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. diff --git a/docs/commands/split.md b/docs/commands/split.md index 8c44518bb1..81392c57e5 100644 --- a/docs/commands/split.md +++ b/docs/commands/split.md @@ -20,30 +20,35 @@ redocly split --version ## Options -| Option | Type | Description | -| ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| api | string | **REQUIRED.** Path to the API description file that you want to split into a multi-file structure. | -| --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. | -| --help | boolean | Show help. | -| --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`). | -| --config | string | Specify path to the [config file](../configuration/index.md). | -| --version | boolean | Show version number. | +| Option | Type | Description | +| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| api | string | **REQUIRED.** Path to the API description file that you want to split into a multi-file structure. | +| --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. | +| --help | boolean | Show help. | +| --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`). | +| --config | string | Specify path to the [config file](../configuration/index.md). | +| --version | boolean | Show version number. | +| --lint-config | string | Specify the severity level for the configuration file.
**Possible values:** `warn`, `error`, `off`. Default value is `warn`. | ## Example {% tabs %} {% tab label="Command" %} + ```bash redocly split pet.yaml --outDir=openapi ``` + {% /tab %} {% tab label="Output" %} + ```bash Document: pet.yaml is successfully split and all related files are saved to the directory: openapi pet.yaml: split processed in 33ms ``` + {% /tab %} {% /tabs %} diff --git a/docs/commands/stats.md b/docs/commands/stats.md index 3ca92e69a0..f8ff33babe 100644 --- a/docs/commands/stats.md +++ b/docs/commands/stats.md @@ -23,13 +23,14 @@ 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.
**Possible values:** `stylish`, `json`. | -| --help | boolean | Show help. | -| --version | boolean | Show version number. | +| 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). | +| --lint-config | string | Specify the severity level for the configuration file.
**Possible values:** `warn`, `error`, `off`. Default value is `warn`. | +| --format | string | Format for the output.
**Possible values:** `stylish`, `json`. | +| --help | boolean | Show help. | +| --version | boolean | Show version number. | ## Examples @@ -51,16 +52,20 @@ Instead of full paths, you can use API names from the `apis` section of your Red {% tabs %} {% tab label="Command" %} + ```bash redocly stats core@v1 ``` + {% /tab %} {% tab label="Configuration file" %} + ```yaml apis: core@v1: root: ./openapi/api-description.json ``` + {% /tab %} {% /tabs %} @@ -77,13 +82,17 @@ redocly stats --config=./another/directory/config.yaml ### Format #### Stylish (default) + {% tabs %} {% tab label="Request" %} + ```bash redocly stats pet.yaml ``` + {% /tab %} {% tab label="Output" %} + ```bash Document: pet.yaml stats: @@ -98,18 +107,23 @@ Document: pet.yaml stats: pet.yaml: stats processed in 6ms ``` + {% /tab %} {% /tabs %} In this format, `stats` shows the statistics for the metrics mentioned in the [Introduction section](#introduction) in condensed output with colored text and an icon at the beginning of each line. #### JSON + {% tabs %} {% tab label="Command" %} + ```bash redocly stats pet.yaml --format=json ``` + {% /tab %} {% tab label="Output" %} + ```bash Output Document: pet.yaml stats: @@ -149,6 +163,7 @@ Document: pet.yaml stats: } pet.yaml: stats processed in 6ms ``` + {% /tab %} {% /tabs %} In this format, `stats` shows the statistics for the metrics mentioned in the [Introduction section](#introduction) in JSON-like output. diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index f2b0ecf288..0243c756d8 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -36,6 +36,11 @@ yargs (yargs) => yargs.positional('api', { type: 'string' }).option({ config: { description: 'Path to the config file.', type: 'string' }, + 'lint-config': { + description: 'Severity level for config file linting.', + choices: ['warn', 'error', 'off'] as ReadonlyArray, + default: 'warn' as RuleSeverity, + }, format: { description: 'Use a specific output format.', choices: ['stylish', 'json'] as ReadonlyArray,