Skip to content

Commit

Permalink
chore: update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@IgorKarpiuk
IgorKarpiuk committed Oct 18, 2023
1 parent 1fee260 commit 65662bd
Show file tree
Hide file tree
Showing 8 changed files with 144 additions and 44 deletions.
25 changes: 13 additions & 12 deletions docs/commands/build-docs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,18 +16,19 @@ 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. |
| --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. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |

## Examples

Expand Down
20 changes: 18 additions & 2 deletions docs/commands/bundle.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`. |
Expand All @@ -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.** |
Expand All @@ -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. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |

## Examples

Expand Down Expand Up @@ -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...
{
Expand All @@ -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...
<?xml version="1.0" encoding="UTF-8"?>
Expand All @@ -160,6 +169,7 @@ bundling pet.yaml...
</checkstyle>
📦 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.
Expand All @@ -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" %}
Expand Down
24 changes: 24 additions & 0 deletions docs/commands/join.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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. <br/> **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.
Expand Down Expand Up @@ -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
Expand All @@ -156,22 +166,28 @@ 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.

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
Expand All @@ -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.
Expand All @@ -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:
Expand Down Expand Up @@ -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.
Expand Down
Loading

0 comments on commit 65662bd

Please sign in to comment.