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

sync: Synced local 'docs/' with remote 'docs/cli/'

Browse Source
This commit is contained in:
redocly-bot
2023-10-09 16:35:49 +00:00
parent eb82725463
commit 9199b2bab7
93 changed files with 905 additions and 660 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/changelog.md
View File

@@ -492,8 +492,7 @@ Technical release for changing the package name from `@redocly/openapi-cli` to `
## 1.0.0-beta.95 (2022-05-04)
:::warning Product name change
{% admonition type="warning" name="Product name change" %}
The product name has changed from OpenAPI CLI to **Redocly CLI**.
This change is reflected in all Redocly product documentation, in the npm package name (more on that in the "Deprecated" section),
@@ -504,7 +503,7 @@ The change also affects the CLI commands. The legacy name `openapi` is supported
If you encounter any issues and suspect they may be related to this change, let us know by [reporting an issue](https://github.com/Redocly/redocly-cli/issues).
:::
{% /admonition %}
### Features
@@ -769,7 +768,7 @@ rules:
### Features
- Added support for the [region](./configuration/index.mdx) option with the `login`, `push`, and other commands.
- Added support for the [region](./configuration/index.md) option with the `login`, `push`, and other commands.
- Added two new built-in rules:
- [no-invalid-schema-examples](./rules/no-invalid-schema-examples.md)
- [no-invalid-parameter-examples](./rules/no-invalid-parameter-examples.md)
@@ -950,7 +949,7 @@ lint:
### Features
- Updated and improved the [introductory content](index.mdx) and [installation instructions](installation.md) for OpenAPI CLI as part of our Google Season of Docs 2021 project.
- Updated and improved the [introductory content](index.md) and [installation instructions](installation.md) for OpenAPI CLI as part of our Google Season of Docs 2021 project.
- Implemented improvements to the internal CD process.

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

@@ -62,7 +62,7 @@ The `build-docs` command uses any additional configurations provided in the file
### Custom configuration file
By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.mdx) in the current working directory. Use the optional `--config` argument to provide an alternative path to a 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 build-docs --config=./another/directory/config.yaml

54
docs/commands/bundle.md
View File

@@ -72,11 +72,9 @@ A fully dereferenced bundle does not use `$ref` at all, all the references are r
redocly bundle --dereferenced --output dist --ext json openapi/openapi.yaml openapi/petstore.yaml
```
:::warning Note
{% admonition type="warning" name="Note" %}
JSON output only works when there are no circular references.
:::
{% /admonition %}
### Custom configuration file
@@ -111,11 +109,14 @@ The compressed output omits other contexts and suggestions.
#### JSON
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly bundle pet.yaml store.yaml -o ./bundled --format=json
```
```bash Output
{% /tab %}
{% tab label="Output" %}
```bash
bundling pet.yaml...
{
"totals": {
@@ -137,16 +138,20 @@ 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
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly bundle pet.yaml -o ./bundled --lint --format=checkstyle
```
```bash Output
{% /tab %}
{% tab label="Output" %}
```bash
bundling pet.yaml...
<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="4.3">
@@ -155,7 +160,8 @@ 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.
Due to the limitations of this format, the output _only_ includes the filename, line, column, severity,
and rule ID (in the `source` attribute).
@@ -164,21 +170,23 @@ All other information is omitted.
### Skip preprocessor, rule, or decorator
You may want to skip specific preprocessors, rules, or decorators upon running the command.
```bash Skip preprocessors
{% tabs %}
{% tab label="Skip preprocessors" %}
```bash
redocly bundle --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example
```
```bash Skip rules
{% /tab %}
{% tab label="Skip rules" %}
```bash
redocly bundle --skip-rule=no-sibling-refs --skip-rule=no-parent-tags
```
```bash Skip decorators
{% /tab %}
{% tab label="Skip decorators" %}
```bash
redocly bundle --skip-decorator=generate-code-samples --skip-decorator=remove-internal-operations
```
:::success Tip
{% /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 %}

2
docs/commands/index.md
View File

@@ -58,4 +58,4 @@ You can also specify a config file to most commands using `--config myconfig.yam
redocly lint --config redocly-official.yaml openapi.yaml
```
For more information, refer to the [Redocly configuration file](../configuration/index.mdx) docs.
For more information, refer to the [Redocly configuration file](../configuration/index.md) docs.

77
docs/commands/join.md
View File

@@ -1,18 +1,12 @@
---
tocMaxDepth: 3
---
# `join`
## Introduction
:::warning Important
{% admonition type="warning" name="Important" %}
The `join` command is considered an experimental feature. This means it's still a work in progress and may go through major changes.
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.
@@ -42,7 +36,7 @@ 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. |
| --help | boolean | Show help. |
| --lint | boolean | Lint API description files. |
@@ -54,22 +48,25 @@ redocly join --version
| --without-x-tag-groups | boolean | Skip automated `x-tagGroups` creation. See the [without-x-tag-groups](#without-x-tag-groups) section. |
| --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.mdx). |
| --config | string | Specify path to the [config file](../configuration/index.md). |
## Examples
### Array of paths
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly join first-api.yaml second-api.json
```
```bash Output
{% /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.
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:
@@ -101,13 +98,12 @@ x-tagGroups:
description: 'Text from info: description of the second input file'
```
:::info
{% 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.
If any of the input files contain the `x-tagGroups` object, the content of this object is ignored by the `join` command and not included in the output file.
:::
{% /admonition %}
The `servers` object combines the content from all input files, starting with the content from the first file. Commented lines are not included in the output file.
@@ -133,11 +129,9 @@ Please fix conflicts before running join.
Use the [`--without-x-tag-groups`](#without-x-tag-groups) option to skip the creation and population of `x-tagGroups` in the output file.
:::warning
{% 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
@@ -146,12 +140,14 @@ 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
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly join first-api.yaml second-api.json --prefix-tags-with-info-prop title
```
```yaml Output file example
{% /tab %}
{% tab label="Output file example" %}
```yaml
- name: First Document title_endpoints
description: endpoints tag description
x-displayName: endpoints
@@ -160,7 +156,8 @@ 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.
@@ -168,12 +165,14 @@ 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
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly join first-api.yaml second-api.json --prefix-tags-with-filename true
```
```yaml Output file example
{% /tab %}
{% tab label="Output file example" %}
```yaml
- name: first-api_endpoints
description: endpoints tag description
x-displayName: endpoints
@@ -182,7 +181,8 @@ 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,12 +206,14 @@ 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
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly join first-api.yaml second-api.json --prefix-components-with-info-prop version
```
```yaml Output file example
{% /tab %}
{% tab label="Output file example" %}
```yaml
components:
schemas:
1.0.1_Pet:
@@ -244,7 +246,8 @@ 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.

147
docs/commands/lint.md
View File

@@ -6,11 +6,9 @@ Redocly CLI can identify and report on problems found in OpenAPI descriptions. T
The `lint` command reports on problems and executes preprocessors and rules. Unlike the `bundle` command, `lint` doesn't execute decorators.
:::success Tip
{% admonition type="success" name="Tip" %}
To learn more about choosing and configuring linting rules to meet your needs, visit the [API standards](../api-standards.md) page.
:::
{% /admonition %}
## Usage
@@ -57,28 +55,34 @@ The `apis` argument can also use any glob format supported by your file system.
#### An API from the configuration file
Instead of full paths, you can use names listed in the `apis` section of your Redocly configuration file.
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint core@v1
```
```yaml Configuration file
{% /tab %}
{% tab label="Configuration file" %}
```yaml
apis:
core@v1:
root: ./openapi/api-description.json
```
{% /tab %}
{% /tabs %}
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.
#### All configured APIs
You can omit apis completely when executing the `lint` command to check all APIs defined in the configuration file.
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint
```
```yaml Configuration file
{% /tab %}
{% tab label="Configuration file" %}
```yaml
apis:
core@v1:
root: ./openapi/api-description.json
@@ -87,18 +91,17 @@ apis:
sandbox:
root: ./openapi/sandbox.yaml
```
{% /tab %}
{% /tabs %}
In this case, if no API descriptions are specified, `lint` validates all apis listed under `apis` in your Redocly configuration file. The presence of the configuration file is mandatory.
:::warning Important
{% admonition type="warning" name="Important" %}
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
By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.mdx) in the current working directory. Use the optional `--config` argument to provide an alternative path to a 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 lint --config=./another/directory/config.yaml
@@ -108,31 +111,29 @@ redocly lint --config=./another/directory/config.yaml
The `--extends` option allows you to extend the existing configuration. This option accepts one of the following values: `minimal`, `recommended`, 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.
:::warning Important
{% 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.
:::
{% /admonition %}
### Format lint output
The standard codeframe output format works well in most situations, but `redocly` can also produce output to integrate with other tools.
:::warning Lint one API at a time
{% 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.
:::
{% /admonition %}
#### Codeframe (default)
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint --format=codeframe
## equivalent to: redocly lint
```
```bash Output
{% /tab %}
{% tab label="Output" %}
```bash
[1] resources/petstore-with-errors.yaml:16:3 at #/paths/~1pets?id
Don't put query string items in the path, they belong in parameters with `in: query`.
@@ -146,35 +147,41 @@ Don't put query string items in the path, they belong in parameters with `in: qu
Error was generated by the path-not-include-query rule.
```
{% /tab %}
{% /tabs %}
Note that the problems are displayed in the following format: `file:line:column`. For example, `petstore-with-errors.yaml:16:3`.
Depending on the terminal emulator you use, it may be possible to directly click this indicator to edit the file in place.
#### Stylish
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint --format=stylish
```
```bash Output
{% /tab %}
{% tab label="Output" %}
```bash
openapi/core.yaml:
15:7 error spec Property `operationIds` is not expected here.
22:11 error spec Property `require` is not expected here.
14:7 warning operation-operationId Operation object should contain `operationId` field.
```
{% /tab %}
{% /tabs %}
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.
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint --format=json
```
```bash Output
{% /tab %}
{% tab label="Output" %}
```bash
{
"totals": {
"errors": 1,
@@ -216,15 +223,19 @@ redocly lint --format=json
]
}
```
{% /tab %}
{% /tabs %}
#### Checkstyle
The `lint` command also supports the [Checkstyle](https://checkstyle.org/) XML report format.
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint --format=checkstyle
```
```bash Output
{% /tab %}
{% tab label="Output" %}
```bash
<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="4.3">
<file name="openapi/core.yaml">
@@ -234,7 +245,8 @@ redocly lint --format=checkstyle
</file>
</checkstyle>
```
{% /tab %}
{% /tabs %}
Due to the limitations of this format, only file name, line, column, severity,
and rule ID (in the `source` attribute) are included. All other information is
omitted.
@@ -242,34 +254,41 @@ omitted.
### <a id="max-problems"></a>Limit the problem 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.
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint --max-problems 200
```
```bash Output
{% /tab %}
{% tab label="Output" %}
```bash
...
< ... 2 more problems hidden > increase with `--max-problems N`
```
{% /tab %}
{% /tabs %}
### Generate ignore file
With this option, you can generate the `.redocly.lint-ignore.yaml` file to suppress error and warning severity problems in the output. You still receive visual feedback to let you know how many problems were ignored.
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.
```shell Command
{% tabs %}
{% tab label="Command" %}
```shell
redocly lint openapi/petstore.yaml --generate-ignore-file
```
```bash Output
{% /tab %}
{% tab label="Output" %}
```bash
...
Generated ignore file with 3 problems.
```
{% /tab %}
{% /tabs %}
:::warning
{% admonition type="warning" %}
This command overwrites an existing ignore file.
:::
{% /admonition %}
To generate an ignore file for multiple API descriptions, pass them as arguments:
@@ -295,18 +314,22 @@ The rule in the example is named `spec`, which indicates compliance with the Ope
### Skip preprocessor or rule
You may want to skip specific preprocessors or rules upon running the command.
```bash Skip preprocessors
{% tabs %}
{% tab label="Skip preprocessors" %}
```bash
redocly lint --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example
```
```bash Skip rules
{% /tab %}
{% tab label="Skip rules" %}
```bash
redocly lint --skip-rule=no-sibling-refs --skip-rule=no-parent-tags
```
{% /tab %}
{% /tabs %}
:::success Tip
{% 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

22
docs/commands/login.md
View File

@@ -12,11 +12,9 @@ If you're having issues with the `login` command, use the `--verbose` option to
## Usage
:::warning Note
{% admonition type="warning" name="Note" %}
Go ahead and [generate a personal API key](../../settings/personal-api-keys.md); this key is needed to log in.
:::
{% /admonition %}
```bash
redocly login [--help] [--verbose] [--version]
@@ -29,25 +27,29 @@ redocly login --verbose
| Option | Type | Description |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| --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.mdx). |
| --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. |
| --config | string | Specify path to the [config file](../configuration/index.mdx). |
| --config | string | Specify path to the [config file](../configuration/index.md). |
## Examples
```bash Successful login
{% tabs %}
{% tab label="Successful login" %}
```bash
redocly login
🔑 Copy your API key from https://app.redocly.com/profile and paste it below:
Logging in...
Authorization confirmed. ✅
```
```bash Failed login
{% /tab %}
{% tab label="Failed login" %}
```bash
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 %}

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

@@ -6,9 +6,9 @@ With this command, you can generate documentation previews for API descriptions
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/).
:::success Tip
{% admonition type="success" name="Tip" %}
To preview docs using the premium Redocly API reference docs, you must first authenticate to the API registry with the [`login`](./login.md) command.
:::
{% /admonition %}
## Usage
@@ -51,22 +51,26 @@ In this case, `preview-docs` previews the API description that was passed to the
#### Pass api alias
Instead of a full path, you can use an API name from the `apis` section of your Redocly configuration file.
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly preview-docs core@v1
```
```yaml Configuration file
{% /tab %}
{% tab label="Configuration file" %}
```yaml
apis:
core@v1:
root: ./openapi/api-description.json
```
{% /tab %}
{% /tabs %}
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.
### Custom configuration file
By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.mdx) in the current working directory. Use the optional `--config` argument to provide an alternative path to a 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
@@ -77,14 +81,18 @@ redocly preview-docs --config=./another/directory/config.yaml
By default, without using the `port` option, the preview starts on port `8080`, so you can access the docs at `http://localhost:8080`
To specify a custom port for the preview, pass the desired value using either short or long option format:
```bash Short format
{% tabs %}
{% tab label="Short format" %}
```bash
redocly preview-docs -p 8888 openapi/openapi.yaml
```
```bash Long format
{% /tab %}
{% tab label="Long format" %}
```bash
redocly preview-docs -port 8888 openapi/openapi.yaml
```
{% /tab %}
{% /tabs %}
Both commands start the preview on port `8888`, so you can access the docs at `http://localhost:8888`.
@@ -93,25 +101,33 @@ Both commands start the preview on port `8888`, so you can access the docs at `h
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`.
To specify a custom host for the preview, pass the desired value using either short or long option format:
```bash Short format
{% tabs %}
{% tab label="Short format" %}
```bash
redocly preview-docs -h 0.0.0.0 openapi/openapi.yaml
```
```bash Long format
{% /tab %}
{% tab label="Long format" %}
```bash
redocly preview-docs --host 0.0.0.0 openapi/openapi.yaml
```
{% /tab %}
{% /tabs %}
Both commands start the preview on host `0.0.0.0`, so you can access the docs at `http://0.0.0.0:8080`
### Skip preprocessor or decorator
You may want to skip specific preprocessors, rules, or decorators upon running the command.
```bash Skip preprocessors
{% tabs %}
{% tab label="Skip preprocessors" %}
```bash
redocly preview-docs --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example
```
```bash Skip decorators
{% /tab %}
{% tab label="Skip decorators" %}
```bash
redocly preview-docs --skip-decorator=generate-code-samples --skip-decorator=remove-internal-operations
```
{% /tab %}
{% /tabs %}

76
docs/commands/push.md
View File

@@ -13,25 +13,21 @@ This allows you to:
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:
- the [Redocly configuration file](../configuration/index.mdx) and any configuration files referenced in the `extends` list.
- 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.
:::attention
{% 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.
Make sure that each plugin has all the required files in its folder; otherwise, they are not uploaded.
:::
{% /admonition %}
By default, the `push` command only updates an existing API description version. If an API with the provided name and version doesn't exist in your organization, it isn't created automatically. For details on how to create an API, check the [Upsert an API with push](#upsert-an-api-with-push) section.
:::warning
Only API descriptions with a CI source can be updated with the `push` command. Attempting to update API descriptions created from other sources fails with an error.
:::
{% admonition type="warning" %}
Only API descriptions with a CI source can be updated with the `push` command. Attempting to update API definitions created from other sources fails with an error.
{% /admonition %}
## Prerequisites
@@ -122,11 +118,9 @@ 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`.
:::warning Note
{% 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 %}
#### API name and version
@@ -137,11 +131,9 @@ 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.
:::attention
{% 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:
@@ -152,11 +144,9 @@ To find your API version required for the command:
When using the `push` command, you would provide the API name and version separated with the "at" symbol (`@`). For example: `--destination=petstore-api@v1`.
:::attention
{% 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 %}
### Set options explicitly
@@ -210,29 +200,36 @@ In this case, you don't have to specify the organization ID in the configuration
### Upsert an API with push
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.
```bash Set options explicitly
{% tabs %}
{% tab label="Set options explicitly" %}
```bash
redocly push -u test-api-v1.yaml --destination=test-api@v1 --organization=redocly
```
```bash Use config file
{% /tab %}
{% tab label="Use config file" %}
```bash
redocly push -u --destination=test-api@v1
```
```bash Upsert all APIs from config file
{% /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`.
```bash Set options explicitly
{% 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.
@@ -253,15 +250,18 @@ Must be used only in combination with the `--job-id` option. Must be an integer
### Skip decorator
You may want to skip specific decorators upon running the command.
```bash Skip a decorator
{% 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
```
```bash Skip multiple decorators
{% /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.

17
docs/commands/split.md
View File

@@ -6,9 +6,9 @@ The `split` command takes an API description file and creates a [multi-file stru
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.
:::warning OpenAPI 3.x only
{% admonition type="warning" name="OpenAPI 3.x only" %}
The `split` command doesn't support OpenAPI 2.0 descriptions.
:::
{% /admonition %}
## Usage
@@ -26,20 +26,25 @@ redocly split --version
| --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.mdx). |
| --config | string | Specify path to the [config file](../configuration/index.md). |
| --version | boolean | Show version number. |
## Example
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly split pet.yaml --outDir=openapi
```
```bash Output
{% /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 %}
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.

37
docs/commands/stats.md
View File

@@ -49,21 +49,26 @@ In this case, `stats` shows statistics for the API description that was passed t
Instead of full paths, you can use API names from the `apis` section of your Redocly configuration file.
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly stats core@v1
```
```yaml Configuration file
{% /tab %}
{% tab label="Configuration file" %}
```yaml
apis:
core@v1:
root: ./openapi/api-description.json
```
{% /tab %}
{% /tabs %}
In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `stats` displays statistics for the `api-description.json` file. The presence of the Redocly configuration file is mandatory.
### Custom configuration file
By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.mdx) in the current working directory. Use the optional `--config` argument to provide an alternative path to a 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 stats --config=./another/directory/config.yaml
@@ -72,12 +77,14 @@ redocly stats --config=./another/directory/config.yaml
### Format
#### Stylish (default)
```bash Request
{% tabs %}
{% tab label="Request" %}
```bash
redocly stats pet.yaml
```
```bash Output
{% /tab %}
{% tab label="Output" %}
```bash
Document: pet.yaml stats:
🚗 References: 3
@@ -91,15 +98,18 @@ 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
```bash Command
{% tabs %}
{% tab label="Command" %}
```bash
redocly stats pet.yaml --format=json
```
{% /tab %}
{% tab label="Output" %}
```bash Output
Document: pet.yaml stats:
@@ -139,5 +149,6 @@ 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.

22
docs/configuration/apis.mdx → docs/configuration/apis.md
View File

@@ -1,7 +1,3 @@
import { JsonSchema } from '@redocly/developer-portal/ui';
import ApiSchema from './api.yaml';
import { StyledContent } from '../../components/styled.elements';
# Per-API configuration
The `apis` object is used to configure one or more APIs.
@@ -17,14 +13,12 @@ If per-API and root settings modify the same properties, per-API settings overri
## Patterned properties
<StyledContent>
<JsonSchema
schema={ApiSchema}
options={{
{% json-schema
schemaFilePath="./api.yaml"
options={
schemaExpansionLevel: 2,
}}
/>
</StyledContent>
}
/%}
## Example
@@ -38,8 +32,6 @@ apis:
openapi: {}
```
:::warning Important
{% admonition type="warning" name="Important" %}
Per-API configurations take priority over global settings.
:::
{% /admonition %}

45
docs/configuration/index.mdx → docs/configuration/index.md
View File

@@ -1,20 +1,17 @@
---
title: Redocly CLI configuration
description: Learn how to configure Redocly CLI
redirectFrom:
- /docs/cli/configuration/configuration-file/
- /docs/cli/guides/lint/
- /docs/cli/configuration/lint/
redirects:
'/docs/cli/configuration/configuration-file/':
to: '/docs/cli/configuration/'
'/docs/cli/guides/lint/':
to: '/docs/cli/configuration/'
'/docs/cli/configuration/lint/':
to: '/docs/cli/configuration/'
toc:
maxDepth: 3
---
import { JsonSchema } from '@redocly/developer-portal/ui';
import Schema from './schema.yaml';
import MockServerSchema from './mockserver.yaml';
import ResolveSchema from './resolve.yaml';
import { StyledContent } from '../../components/styled.elements';
# Redocly configuration file
You can configure all of your Redocly tools using a single `redocly.yaml` configuration file in the root of your project. Your `redocly.yaml` configurations can be used locally, in CI, or on our hosted platforms to specify the following behaviors:
@@ -133,14 +130,12 @@ This object is optional.
#### Fixed properties
<StyledContent>
<JsonSchema
schema={MockServerSchema}
options={{
{% json-schema
schemaFilePath="./mockserver.yaml"
options={
schemaExpansionLevel: 1,
}}
/>
</StyledContent>
}
/%}
#### openapi object
@@ -148,7 +143,7 @@ The `openapi` object is a property of the `theme` object and configures features
If you need to apply different theming and functionality to individual APIs, add the theme `openapi` property to the appropriate API in the `apis` and `theme` object, and use the same options as the global `openapi` object.
Find the full list of supported options on the [Reference docs configuration page](../../api-reference-docs/configuration/functionality.mdx).
Find the full list of supported options on the [Reference docs configuration page](../../api-reference-docs/configuration/functionality.md).
<a id="apis-object"></a>
@@ -177,7 +172,7 @@ apis:
remove-x-internal: on
```
Visit the [per-API configuration page](./apis.mdx) for detailed documentation and more examples.
Visit the [per-API configuration page](./apis.md) for detailed documentation and more examples.
<a id="plugins-list"></a>
@@ -213,14 +208,12 @@ Redocly CLI supports one `http` header per URL.
#### Fixed properties
<StyledContent>
<JsonSchema
schema={ResolveSchema}
options={{
{% json-schema
schemaFilePath="./resolve.yaml"
options={
schemaExpansionLevel: 2,
}}
/>
</StyledContent>
}
/%}
#### Example

6
docs/custom-plugins/custom-config.md
View File

@@ -41,11 +41,9 @@ extends:
Plugins can include rules, decorators, and preprocessors in their configuration bundles.
:::info Rulesets
{% admonition type="info" name="Rulesets" %}
If your configuration includes only Redocly built-in rules and decorators, try
using a [ruleset](../rules.md#rulesets) to achieve this (it's simpler than a
plugin).
:::
{% /admonition %}

6
docs/custom-plugins/custom-decorators.md
View File

@@ -7,11 +7,9 @@ Decorators transform API descriptions, by adding, removing, or changing elements
If you can't find an existing decorator that fits your needs, then you can add a decorator in a plugin.
:::warning Preprocessors
{% admonition type="warning" name="Preprocessors" %}
Decorators and preprocessors are the same in structure, but preprocessors are run _before_ linting, and decorators are run after. We always recommend using decorators where possible, since the document might not be valid or structured as expected if the linting step hasn't run yet.
:::
{% /admonition %}
## Plugin structure

23
docs/custom-plugins/index.md
View File

@@ -1,9 +1,12 @@
---
title: Custom plugins in Redocly
redirectFrom:
- /docs/cli/custom-rules/
- /docs/cli/resources/custom-rules/
- /docs/cli/resources/custom-plugins/
redirects:
'/docs/cli/custom-rules/':
to: '/docs/cli/custom-plugins/'
'/docs/cli/resources/custom-rules/':
to: '/docs/cli/custom-plugins/'
'/docs/cli/resources/custom-plugins/':
to: '/docs/cli/custom-plugins/'
---
# Custom plugins
@@ -12,9 +15,9 @@ Custom plugins are a powerful way to extend Redocly. Use of custom plugins requi
Custom plugins are recommended for advanced users who have exhausted the built-in options available, and who can develop JavaScript extensions themselves.
Each plugin is a JavaScript module which can export custom rules, configurations, preprocessors, decorators or type tree extensions.
:::info
{% admonition type="info" %}
For many users, our highly [configurable rules](../rules/configurable-rules.md) cover their needs without needing a custom plugin.
:::
{% /admonition %}
Custom plugins use the [visitor pattern](./visitor.md) to traverse the document structure and apply the rules and decorators (and preprocessors if you have them) to each element. Rules defined in custom plugins may need additional context available, and this can be achieved using the [nested visitor approach](./visitor.md#nested-visitors) (please note that nested visitors are not available for decorators or preprocessors).
@@ -30,7 +33,6 @@ Custom plugins can extend the built-in functionality of Redocly in the following
- **Write custom decorators in JavaScript**. Not all API descriptions are exactly as we'd like them to be before passing them to the next stage of the API lifecycle. Redocly has a selection of [decorators available](../decorators), but if you need to build something more then [visit the documentation for building decorators in custom plugins](./custom-decorators.md).
### Order of execution
Some commands, such as using `bundle` with `--lint`, may execute more than one type of functionality. The order is preprocessors first, then linting rules, and finally the decorators are applied.
@@ -44,7 +46,6 @@ graph LR
style V fill:#codaf9,stroke:#0044d4,stroke-width:4px
```
## Add custom plugins to your project
Each plugin can contain any or many of each type of extension (rules, configuration, decorators, etc).
@@ -52,7 +53,6 @@ Each plugin can contain any or many of each type of extension (rules, configurat
Define the plugins to include in the `redocly.yaml` configuration file, in the `plugins` section:
```yaml
plugins:
- plugins/my-best-plugin.js
- plugins/another-plugin.js
@@ -60,15 +60,14 @@ plugins:
The paths are relative to the configuration file location. Where there are multiple features that happen at the same time, such as decorators, the plugins loaded first in the `plugins` section are processed first.
### Plugin structure
The minimal plugin should export an `id` string that is used to refer to the contents of the plugin in the `redocly.yaml` configuration file:
```js
module.exports = {
id: 'my-local-plugin'
}
id: 'my-local-plugin',
};
```
## Supported formats

4
docs/custom-plugins/visitor.md
View File

@@ -70,9 +70,9 @@ The `Schema` **visitor function** is called by Redocly CLI only if the Schema Ob
As the third argument, `enter()` in a **nested visitor object** accepts the `parents` object with corresponding parent nodes as defined in the **visitor object**.
:::attention
{% admonition type="attention" %}
It is executed only for the first level of the Schema Object.
:::
{% /admonition %}
For the example document below:

15
docs/decorators.md
View File

@@ -1,14 +1,16 @@
---
redirectFrom:
- /docs/cli/resources/built-in-decorators/
redirects:
'/docs/cli/resources/built-in-decorators/':
to: '/docs/cli/decorators'
---
# Decorators
Decorators are a way of changing an API description during bundling. This updating during bundling can be useful for the following use cases:
* removing some endpoints from an OpenAPI description before publishing
* updating description fields
* adding extra elements, such as examples, or metadata for other tools to use
- removing some endpoints from an OpenAPI description before publishing
- updating description fields
- adding extra elements, such as examples, or metadata for other tools to use
To learn how to configure decorators, read more about their [configuration syntax](#decorator-configuration-syntax).
@@ -40,7 +42,7 @@ Open a [GitHub issue](https://github.com/Redocly/redocly-cli/issues/new?assignee
## Decorator configuration syntax
The following example shows how to configure a decorator in the [Redocly configuration file](./configuration/index.mdx).
The following example shows how to configure a decorator in the [Redocly configuration file](./configuration/index.md).
```yaml
apis:
@@ -59,4 +61,3 @@ Optionally, you may specify `severity` as one of decorator options in the config
## Custom decorators
If you don't see the decorator you need, you can create your own decorators using [custom plugins](./custom-plugins/custom-decorators.md).

8
docs/file-management.md
View File

@@ -37,15 +37,15 @@ redocly bundle openapi.yaml -o bundled.yaml
All the references are brought into a single file, that you can then pass on to other tools in your API workflow.
:::info
{% admonition type="info" %}
Pass `--lint` to the bundle command to have Redocly CLI check your API meets the expected standards before bundling. [Learn more about API standards and linting](./api-standards.md)
:::
{% /admonition %}
## Combine OpenAPI files
:::warning
{% admonition type="warning" %}
This feature is experimental, and supports OpenAPI 3.x only
:::
{% /admonition %}
When you have multiple APIs but want to publish a single API description file, the [`join`](./commands/join.md) may meet your needs. This can be useful when you are providing a combined offering and want to create unified documentation, or use a single input to other tools.

33
docs/guides/change-token-url.md
View File

@@ -1,28 +1,32 @@
---
redirectFrom:
- /docs/resources/change-token-url/
redirects:
'/docs/resources/change-token-url/':
to: '/docs/cli/guides/change-token-url'
---
# Change OAuth2 token URL
Use a custom decorator to change the OAuth2 credentials flow token URL.
Estimated time: 15 minutes
## Step-by-step instructions
1. Add this code to your repo with the API (the Redocly configuration file is an example).
```yaml redocly.yaml
{% tabs %}
{% tab label="redocly.yaml" %}
```yaml
extends:
- recommended
plugins:
- './acme-plugin.js'
decorators:
plugin/change-token-url:
tokenUrl: "https://token.example.com/url"
tokenUrl: 'https://token.example.com/url'
```
```js acme-plugin.js
{% /tab %}
{% tab label="acme-plugin.js" %}
```js
const ChangeTokenUrl = require('./decorators/change-token-url');
const id = 'plugin';
@@ -38,20 +42,23 @@ Estimated time: 15 minutes
decorators,
};
```
```js decorators/change-token-url.js
{% /tab %}
{% tab label="decorators/change-token-url.js" %}
```js
module.exports = ChangeTokenUrl;
/** @type {import('@redocly/cli').OasDecorator} */
function ChangeTokenUrl({tokenUrl}) {
function ChangeTokenUrl({ tokenUrl }) {
return {
OAuth2Flows: {
leave(flows, ctx) {
if (tokenUrl) {
flows.clientCredentials.tokenUrl = tokenUrl;
}
}
}
}
},
},
};
}
```
{% /tab %}
{% /tabs %}

4
docs/guides/configure-rules.md
View File

@@ -35,9 +35,9 @@ extends:
The configuration here is _very_ minimal with only the ruleset defined so far. Your config file also holds settings for themes, much more detailed configuration for linting and decorating, and custom plugins.
:::attention
{% admonition type="attention" %}
You can also define rulesets and other linting details differently for each API if you need to.
:::
{% /admonition %}
## Adjust the rules in use

18
docs/guides/hide-apis.md
View File

@@ -1,8 +1,10 @@
---
tocMaxDepth: 3
redirectFrom:
- /docs/resources/hide-apis/
redirects:
'/docs/resources/hide-apis/':
to: '/docs/cli/guides/hide-apis/'
---
# Hide your internal APIs
Several times a month, a variation of this question comes up:
@@ -27,9 +29,9 @@ The following image highlights what is to be removed in this tutorial.
## Prerequisites
:::note We do, You do
{% admonition type="note" name="We do, You do" %}
This tutorial is most effective when you follow along and complete the steps.
:::
{% /admonition %}
- [Install @redocly/cli](../installation.md) with version 1.0.0-beta.90 or later (we use 1.0.0-beta.94 in this tutorial).
- Download the [sample.yaml](https://gist.github.com/adamaltman/ee07bf94a967926ee0e54bcd56fdcdfb) file into a new directory named `hide-apis-demo`.
@@ -88,6 +90,7 @@ apis:
external@latest:
root: ./sample.yaml
```
Finally, we want the [remove-x-internal](../decorators/remove-x-internal.md) decorator to be applied to the external API.
To accomplish that, add the last three lines as shown in the following example.
@@ -123,6 +126,7 @@ This can be done in two ways:
1. Confirm the API in the registry has the appropriate content.
1. Repeat this step for each API.
### Option B: Use your machine and the `bundle` command
1. Bundle the `external@latest` API.
@@ -138,8 +142,10 @@ This can be done in two ways:
```shell
redocly bundle internal@latest --output dist/internal.yaml
```
Inspect the file at `dist/internal.yaml`.
Confirm the following:
- The `postStars` operation is **not** removed.
- The `hasPlanets` property is **not** removed.
@@ -150,7 +156,7 @@ Be sure to tag `@Redocly` as it lets us know how we're doing and where we can im
Try this technique with your own APIs to accomplish the use case demonstrated above.
:::danger Security through obscurity
{% admonition type="danger" name="Security through obscurity" %}
If an endpoint is discovered, your API authentication mechanism **must** prevent unauthorized access.
Removing APIs from documentation is not a security mechanism. Use access controls for your internal API documentation as well.
:::
{% /admonition %}

12
docs/guides/hide-specification-extensions.md
View File

@@ -19,9 +19,9 @@ For this tutorial, we've prepared a sample containing OpenAPI specification exte
## Prerequisites
:::note We do, You do
{% admonition type="note" name="We do, You do" %}
This tutorial is most effective when you follow along and complete the steps.
:::
{% /admonition %}
- [Install @redocly/cli](../installation.md) with version 1.0.0-beta.117 or later (we use 1.0.0-beta.117 in this tutorial).
- Download the [sample.yaml](https://gist.github.com/bandantonio/e1331ba5afd24485de5e6229c91d25ed) file into a new directory named `hide-openapi-extensions`.
@@ -52,9 +52,9 @@ In this step, create a custom plugin and define the decorator dependency.
1. Save the file.
:::attention
{% admonition type="attention" %}
You can name the plugins directory and the file anything you want. Make sure you use the correct name in the Redocly configuration file (Step 3 below).
:::
{% /admonition %}
## Step 2: Add a decorator and associate it with an environment variable
@@ -86,9 +86,9 @@ You can name the plugins directory and the file anything you want. Make sure you
1. Save the file.
:::attention
{% admonition type="attention" %}
You can name the decorators directory anything you want. Make sure you use the correct directory name in the line 1 of the `plugin.js` file (Step 1 above).
:::
{% /admonition %}
## Step 3: Configure the plugin for use

33
docs/guides/index.md Normal file
View File

@@ -0,0 +1,33 @@
---
title: Redocly CLI guides
description: Browse how-to guides for working with Redocly CLI
content:
cards:
- header: Redocly CLI quickstart
link: docs/api-registry/cli/quickstart
text: Take your first steps with Redocly CLI.
- header: OpenAPI starter project
link: docs/api-registry/cli/openapi-starter
text: Get started with OpenAPI and Redocly, using this sample project.
- header: Enforce response contents
link: docs/api-registry/cli/guides/response-contains-property
text: How to create a custom rule to enforce response contents.
- header: Hide internal APIs
link: docs/api-registry/cli/guides/hide-apis
text: How to hide internal APIs.
- header: Replace the server URL
link: docs/api-registry/cli/guides/replace-servers-url
text: How to replace the server URL in different environments.
- header: Change the OAuth2 token URL
link: docs/api-registry/cli/guides/change-token-url
text: How to change the OAuth2 token URL.
- header: Hide OpenAPI specification extensions
link: docs/api-registry/cli/guides/hide-specification-extensions
text: How to create a custom decorator to hide OpenAPI specification extensions.
---
# Redocly CLI guides
A selection of guides to common tasks with Redocly CLI.
{% wideTileCards content=$frontmatter.content /%}

36
docs/guides/index.mdx
View File

@@ -1,36 +0,0 @@
---
title: Redocly CLI guides
description: Browse how-to guides for working with Redocly CLI
---
import { WideTile, Flex } from '@redocly/developer-portal/ui';
# Redocly CLI guides
A selection of guides to common tasks with Redocly CLI.
<div>
<Flex justifyContent="space-between" flexWrap="wrap">
<WideTile to="../quickstart.md" header="Redocly CLI quickstart">
Take your first steps with Redocly CLI.
</WideTile>
<WideTile to="../openapi-starter.md" header="OpenAPI starter project">
Get started with OpenAPI and Redocly, using this sample project.
</WideTile>
<WideTile to="./response-contains-property.md" header="Enforce response contents">
How to create a custom rule to enforce response contents.
</WideTile>
<WideTile to="./hide-apis.md" header="Hide internal APIs">
How to hide internal APIs.
</WideTile>
<WideTile to="./replace-servers-url.md" header="Replace the server URL">
How to replace the server URL in different environments.
</WideTile>
<WideTile to="./change-token-url.md" header="Change the OAuth2 token URL">
How to change the OAuth2 token URL.
</WideTile>
<WideTile to="./hide-specification-extensions.md" header="Hide OpenAPI specification extensions">
How to create a custom decorator to hide OpenAPI specification extensions.
</WideTile>
</Flex>
</div>

6
docs/guides/lint-asyncapi.md
View File

@@ -7,11 +7,9 @@ seo:
# Lint AsyncAPI with Redocly CLI
:::info Experimental AsyncAPI support
{% admonition type="info" name="Experimental AsyncAPI support" %}
This feature is at an early stage, please use with caution and send us lots of feedback!
:::
{% /admonition %}
In addition to providing lint functionality for multiple OpenAPI formats, Redocly CLI also has support for AsyncAPI.
Redocly CLI supports the following linting approaches with AsyncAPI documents:

2
docs/guides/migrate-from-openapi-cli.md
View File

@@ -6,4 +6,4 @@ This is the best upgrade path ever:
... that's it. The project and command were renamed, but everything else should just work.
There are some new features in Redocly CLI, so [visit the main docs](../index.mdx) and see if there's anything you'd like to add to your own workflows.
There are some new features in Redocly CLI, so [visit the main docs](../index.md) and see if there's anything you'd like to add to your own workflows.

18
docs/guides/migrate-from-redoc-cli.md
View File

@@ -12,7 +12,7 @@ Visit the [installation page](../installation.md) to find and use an installatio
## Replace old commands with new ones
All Redocly CLI commands use a common configuration file. For theme options, linting rules, and other configuration, check out the [configuration documentation](../configuration/index.mdx) for all the details.
All Redocly CLI commands use a common configuration file. For theme options, linting rules, and other configuration, check out the [configuration documentation](../configuration/index.md) for all the details.
### Developing documentation
@@ -27,9 +27,9 @@ By default the documentation is available on `http://127.0.0.1:8080` but this is
The `--use-community-edition` parameter is needed for the tool to use Redoc to generate the docs; otherwise it generates the preview for our hosted [API reference docs](https://redocly.com/reference/)
:::success Command reference
{% admonition type="success" name="Command reference" %}
Visit the [`preview-docs` documentation](../commands/preview-docs.md) for more information and examples
:::
{% /admonition %}
### Publishing documentation
@@ -49,9 +49,9 @@ If you have your OpenAPI description split between multiple files, replace `redo
redocly bundle openapi.yaml -o all-in-one.yaml
```
:::success Command reference
{% admonition type="success" name="Command reference" %}
Details and examples of using `bundle` are on the [`bundle` command page](../commands/bundle.md). Learn more about bundling, dereferencing, and handling unused components.
:::
{% /admonition %}
## Update configuration settings
@@ -78,7 +78,7 @@ redocly build-docs --theme.openapi.theme.sidebar.width='300px' openapi.yaml
### Update configuration file
Configuration belongs in a file named `redocly.yaml`, or in a file name specified with the `--config` command-line parameter. You can read more about the [configuration file structure](../configuration/index.mdx) in the documentation, and changes between this and older versions are listed here.
Configuration belongs in a file named `redocly.yaml`, or in a file name specified with the `--config` command-line parameter. You can read more about the [configuration file structure](../configuration/index.md) in the documentation, and changes between this and older versions are listed here.
Options named `features.openapi.*` should be re-prefixed to `theme.openapi.*`, either at the top level of the configuration, or per API. So a configuration file to change one of the colours to a rather lurid purple would look something like the example below:
@@ -100,12 +100,12 @@ extends:
## Next steps with Redocly CLI
The newer tool has a lot more functionality than `redoc-cli` had, so explore the rest of the [Redocly CLI documentation](../index.mdx) to find out more about:
The newer tool has a lot more functionality than `redoc-cli` had, so explore the rest of the [Redocly CLI documentation](../index.md) to find out more about:
- Ensuring API quality with linting
- Managing large OpenAPI files
- Enhancing an OpenAPI description with decorators
:::warning Uninstall
{% admonition type="warning" name="Uninstall" %}
It's recommended to uninstall `redoc-cli` now that it is no longer needed
:::
{% /admonition %}

6
docs/guides/migrate-from-spectral.md
View File

@@ -26,7 +26,7 @@ Similar to Spectral, Redocly offers multiple output formats using the `--format`
### Resolvers
If you use `--resolver` to handle how links and remote URLs are resolved, visit the [configuration documentation](../configuration/index.mdx#resolve-object) to see how to handle this with Redocly.
If you use `--resolver` to handle how links and remote URLs are resolved, visit the [configuration documentation](../configuration/index.md#resolve-object) to see how to handle this with Redocly.
## Update configuration
@@ -57,7 +57,7 @@ rules:
message: "Operation summary must not include the word test"
```
It is also possible to configure additional rules for specific APIs using the [APIs object](../configuration/index.mdx#apis-object) to set per-API rules (or exceptions!).
It is also possible to configure additional rules for specific APIs using the [APIs object](../configuration/index.md#apis-object) to set per-API rules (or exceptions!).
### Redocly rules and Spectral equivalents
@@ -141,4 +141,4 @@ For some advanced use cases, the configurable rules can't cover all possibilitie
## Explore tool functionality
Redocly CLI supports multiple Redocly products and functions, so go ahead and [read more about Redocly CLI](../index.mdx).
Redocly CLI supports multiple Redocly products and functions, so go ahead and [read more about Redocly CLI](../index.md).

16
docs/guides/migrate-from-swagger-cli.md
View File

@@ -2,11 +2,9 @@
Redocly CLI is the recommended replacement for the deprecated [swagger-cli](https://www.npmjs.com/package/swagger-cli) package. This guide shows you how to replace the old commands with Redocly CLI commands. Redocly CLI is built for OpenAPI but you can assume that Swagger 2.0 is also supported when the documentation refers to an OpenAPI description. We know those existing APIs are still working hard in many places!
:::success Modern API tooling
{% admonition type="success" name="Modern API tooling" %}
Redocly CLI is open source and actively maintained, supporting newer versions of OpenAPI (3.1) and continuing to evolve. It also provides extensive [linting](../api-standards.md) options, easy and beautiful [API reference documentation](../api-docs.md), and plenty of extensibility with [custom plugins](../custom-plugins/index.md).
:::
{% /admonition %}
## Validate OpenAPI/Swagger files
@@ -48,11 +46,13 @@ redocly lint openapi.yml
You can add more [built-in rules](../rules/built-in-rules.md) by adding them in the configuration file, and adjust the level of the messages by using `warn` rather than `error`.
:::info Redocly configuration
<!-- :::info Redocly configuration -->
Learn more about [configuring Redocly CLI](../configuration/index.mdx) in the documentation.
<!-- :::info Redocly configuration -->
:::
Learn more about [configuring Redocly CLI](../configuration/index.md) in the documentation.
<!-- ::: -->
## Bundle OpenAPI/Swagger into a single file
@@ -78,4 +78,4 @@ Both commands have additional options; here's a quick reference on how to replac
## Get the best from Redocly CLI
Redocly CLI has more functionality than `swagger-cli` did, so if that sounds interesting you should [visit the main docs](../index.mdx) and see if there's anything you'd like to add to your own workflows.
Redocly CLI has more functionality than `swagger-cli` did, so if that sounds interesting you should [visit the main docs](../index.md) and see if there's anything you'd like to add to your own workflows.

38
docs/guides/replace-servers-url.md
View File

@@ -1,9 +1,11 @@
---
redirectFrom:
- /docs/workflows/guides/replace-server-url/
- /docs/cli/guides/replace-server-url/
redirects:
'/docs/workflows/guides/replace-server-url/':
to: '/docs/cli/guides/replace-servers-url/'
'/docs/cli/guides/replace-server-url/':
to: '/docs/cli/guides/replace-servers-url/'
---
---
# Replace servers URL in different environments
Redocly allows you to use [custom decorators](../custom-plugins/custom-decorators.md) to modify content in the API description during the bundling process.
@@ -12,9 +14,9 @@ This page describes how to replace the server URL with a decorator for a given e
## Prerequisites
:::note We do, You do
{% admonition type="note" name="We do, You do" %}
This tutorial is most effective when you follow along and complete the steps.
:::
{% /admonition %}
- [Install @redocly/cli](../installation.md) with version 1.0.0-beta.111 or later (we use 1.0.0-beta.111 in this tutorial).
- Save the following OpenAPI file as `original.yaml` into a new directory named `replace-servers-demo`.
@@ -67,11 +69,9 @@ module.exports = {
3. Save the file.
:::attention
{% admonition type="attention" %}
You can name the plugins directory and file anything you want. Make sure you use the correct name in the Redocly configuration file (Step 3).
:::
{% /admonition %}
## Step 2: Add a decorator and associate it with an environment variable
@@ -100,11 +100,9 @@ function ReplaceServersURL({serverUrl}) {
};
```
:::attention
{% admonition type="attention" %}
You can name the decorators directory anything you want. Make sure you use the correct directory name in line 1 of the `plugin.js` file (Step 1).
:::
{% /admonition %}
## Step 3: Configure the plugin for use
@@ -116,14 +114,14 @@ apis:
root: original.yaml
decorators:
plugin/replace-servers-url:
serverUrl: "https://backend.example.com/v1"
serverUrl: 'https://backend.example.com/v1'
sample@v1-proxy:
root: original.yaml
decorators:
plugin/replace-servers-url:
serverUrl: "https://proxy.example.com/v1"
serverUrl: 'https://proxy.example.com/v1'
plugins:
- "./plugins/plugin.js"
- './plugins/plugin.js'
extends:
- recommended
```
@@ -131,10 +129,13 @@ extends:
## Step 4: Verify the output
The following command bundles the `original.yaml` API with the "backend" server URL.
```yaml
npx @redocly/cli bundle sample@v1-backend
```
The output should show the correct server URL.
```yaml
openapi: 3.1.0
info:
@@ -147,10 +148,13 @@ servers:
```
The following command bundles the `original.yaml` API with the "proxy" server URL.
```yaml
npx @redocly/cli bundle sample@v1-proxy
```
The output should show the correct server URL.
```yaml
openapi: 3.1.0
info:

16
docs/guides/response-contains-property.md
View File

@@ -1,7 +1,8 @@
---
tocMaxDepth: 3
redirectFrom:
- /docs/resources/response-contains-property/
redirects:
'/docs/resources/response-contains-property/':
to: '/docs/cli/guides/response-contains-property/'
---
# Enforce response contents with the `response-contains-property` rule
@@ -21,7 +22,7 @@ Let's get started!
- [Use the openapi-starter repository](../openapi-starter.md) to set up a basic project for use with this guide.
- [Download the modified project files](https://gist.github.com/bandantonio/c6047e3ee70c90da013a2f8e6757edb0) and use them to
replace the corresponding files in the `openapi` folder:
replace the corresponding files in the `openapi` folder:
```bash
.
@@ -37,15 +38,15 @@ replace the corresponding files in the `openapi` folder:
└── users_{username}.yaml
```
:::note
{% admonition type="note" %}
Make sure that the @redocly/cli has version `1.0.0-beta.99` or later
:::
{% /admonition %}
- If you're using VS Code as your favorite code editor, we recommend you install the [Redocly OpenAPI VS Code extension](../../redocly-openapi/index.md).
:::note We do, You do
{% admonition type="note" name="We do, You do" %}
This guide is most effective when you follow along and complete the steps.
:::
{% /admonition %}
## Case 0 - Check that the current OpenAPI description is valid
@@ -236,7 +237,6 @@ rules:
- ref_id
```
```bash npx redocly lint
npx redocly lint

5
docs/guides/update-cli.md
View File

@@ -1,6 +1,7 @@
---
redirectFrom:
- /docs/cli/update-cli/
redirects:
'/docs/cli/update-cli/':
to: '/docs/cli/guides/update-cli'
---
# Update Redocly CLI

41
docs/index.md Normal file
View File

@@ -0,0 +1,41 @@
---
tocMaxDepth: 2
redirects:
'/docs/cli/resources/':
to: '/docs/cli/'
content:
cards:
- header: Great API docs
link: docs/cli/api-docs
text: Use open source Redoc or our hosted tools to create clear and useful documentation with local previews and static builds available.
- header: Manage OpenAPI files
link: docs/cli/file-management
text: Split an OpenAPI description into logical chunks, bundle the chunks to create a single file, or even join existing definitions into one.
- header: Transform OpenAPI
link: docs/cli/decorators
text: Publish a subset of endpoints, or use decorators to enhance your existing OpenAPI by adding, changing, or removing content.
- header: API governance
link: docs/cli/api-standards
text: Check that your API is up to standard on every revision. Our ready-made rulesets, built-in and configurable rules let you compose the API standards that fit each of your APIs.
---
# Redocly CLI
Redocly CLI is an open source command-line tool for working with OpenAPI descriptions, developer portals, and other API lifecycle operations including API linting, enhancement, and bundling.
`redocly` brings together the open source goodness with the rest of the Redocly offerings.
Authenticate, update APIs, publish documentation, and use the other tools to manage, polish and share the APIs throughout the API lifecycle.
{% wideTileCards content=$frontmatter.content /%}
## About Redocly and Redoc
Redoc is our open source API documentation tool. Use `redocly` (this project) to work with your Redoc documentation projects.
The Redocly CLI also supports many of the other operations you need to be successful working with OpenAPI. API linting, enhancement, bundling and other tools are also available as part of this open source CLI tool.
Redocly offers a full suite of API lifecycle tools as commercial offerings; you can manage those from this tool too.
## Want to contribute?
Then join our active and supportive community! The source code is available [on GitHub](https://github.com/Redocly/redocly-cli).

45
docs/index.mdx
View File

@@ -1,45 +0,0 @@
---
tocMaxDepth: 2
redirectFrom:
- /docs/cli/resources/
---
import { WideTile, Flex } from '@redocly/developer-portal/ui';
# Redocly CLI
Redocly CLI is an open source command-line tool for working with OpenAPI descriptions, developer portals, and other API lifecycle operations including API linting, enhancement, and bundling.
`redocly` brings together the open source goodness with the rest of the Redocly offerings.
Authenticate, update APIs, publish documentation, and use the other tools to manage, polish and share the APIs throughout the API lifecycle.
<div>
<Flex justifyContent="space-between" flexWrap="wrap">
<WideTile to="./api-docs.md" header="Great API docs">
Use open source <a href="https://github.com/redocly/redoc" target="_blank">Redoc</a> or our hosted tools to create clear and useful documentation with local previews and static builds available.
</WideTile>
<WideTile to="./file-management.md" header="Manage OpenAPI files">
Split an OpenAPI description into logical chunks, bundle the chunks to create a single file, or even join existing API descriptions into one.
</WideTile>
<WideTile to="./decorators.md" header="Transform OpenAPI">
Publish a subset of endpoints, or use decorators to enhance your existing OpenAPI by adding, changing, or removing content.
</WideTile>
<WideTile to="./api-standards.md" header="API governance">
Check that your API is up to standard on every revision. Our ready-made rulesets, built-in and configurable rules let you compose the API standards that fit each of your APIs.
</WideTile>
</Flex>
</div>
## About Redocly and Redoc
Redoc is our open source API documentation tool. Use `redocly` (this project) to work with your Redoc documentation projects.
The Redocly CLI also supports many of the other operations you need to be successful working with OpenAPI. API linting, enhancement, bundling and other tools are also available as part of this open source CLI tool.
Redocly offers a full suite of API lifecycle tools as commercial offerings; you can manage those from this tool too.
## Want to contribute?
Then join our active and supportive community! The source code is available [on GitHub](https://github.com/Redocly/redocly-cli).

41
docs/installation.md
View File

@@ -8,46 +8,57 @@ Choose the most appropriate installation method for your needs:
## Install globally
:::success Tip
{% admonition type="success" name="Tip" %}
Make sure you have the newest version of `npm`/`yarn` before you begin.
:::
{% /admonition %}
```shell npm
{% tabs %}
{% tab label="npm" %}
```shell
npm i -g @redocly/cli@latest
```
```shell yarn
{% /tab %}
{% tab label="yarn" %}
```shell
yarn global add @redocly/cli
```
{% /tab %}
{% /tabs %}
Running `redocly --version` confirms that the installation was successful, and the currently-installed version of the tool.
## Use `npx` at runtime
[npx](https://docs.npmjs.com/cli/v9/commands/npx/) is npm's package runner. It installs and runs a command without installing it globally. You might use this where you can't install a new command, or in a CI context where the command is only used a handful of times.
```shell Command
{% tabs %}
{% tab label="Command" %}
```shell
npx @redocly/cli <command> [options]
```
```shell Example with lint command
{% /tab %}
{% tab label="Example with lint command" %}
```shell
npx @redocly/cli@latest lint petstore.yaml
```
{% /tab %}
{% /tabs %}
## <a id="docker"></a>Run commands inside Docker
Redocly CLI is available as a pre-built Docker image in [Docker Hub](https://hub.docker.com/r/redocly/cli) and [GitHub Packages](https://github.com/Redocly/redocly-cli/pkgs/container/cli).
Install [Docker](https://docs.docker.com/get-docker/) if you don't have it already, then pull the image with the following command:
```shell Docker Hub
{% tabs %}
{% tab label="Docker Hub" %}
```shell
docker pull redocly/cli
```
```shell GitHub Packages
{% /tab %}
{% tab label="GitHub Packages" %}
```shell
docker pull ghcr.io/redocly/cli
```
{% /tab %}
{% /tabs %}
To give a Docker container access to your OpenAPI description files, you need to mount the containing directory as a volume. Assuming the API description is in the current working directory, the command to use is:
```shell Example with lint command

4
docs/quickstart.md
View File

@@ -6,9 +6,9 @@ Before you start:
* [install the Redocly CLI](./installation.md) if you haven't already
* if you have an OpenAPI description to use, have it handy (we assume it's called `openapi.yaml`), or [try our example](https://github.com/Redocly/openapi-starter/blob/main/openapi/openapi.yaml)
:::attention
{% admonition type="attention" %}
There's also an [openapi-starter](https://github.com/Redocly/openapi-starter) repository that you can clone and experiment with to get your bearings
:::
{% /admonition %}
### Preview API documentation

4
docs/rules/boolean-parameter-prefixes.md
View File

@@ -1,3 +1,7 @@
---
slug: /docs/cli/rules/boolean-parameter-prefixes
---
# boolean-parameter-prefixes
Enforces specific and consistent naming for request parameters with `boolean` type.

21
docs/rules/built-in-rules.md
View File

@@ -1,7 +1,10 @@
---
redirectFrom:
- /docs/cli/built-in-rules/
- /docs/cli/resources/built-in-rules/
redirects:
'/docs/cli/built-in-rules/':
to: '/docs/cli/rules/built-in-rules/'
'/docs/cli/resources/built-in-rules/':
to: '/docs/cli/rules/built-in-rules/'
slug: /docs/cli/rules/built-in-rules
---
# Built-in rules
@@ -9,11 +12,11 @@ redirectFrom:
The built-in rules are the ones we use ourselves and think apply to the majority of APIs. Some have some additional [configuration](#rule-configuration-syntax), but otherwise all you need to do is decide whether each rule should `error`, `warn` or be `off`.
All the built-in rules are listed here, roughly grouped by the OpenAPI object they apply to.
The *Special rules* group contains rules that may apply to multiple objects or to the entire OpenAPI document.
The _Special rules_ group contains rules that may apply to multiple objects or to the entire OpenAPI document.
:::info
{% admonition type="info" %}
Build [configurable rules](./configurable-rules.md) if the rule you need isn't listed.
:::
{% /admonition %}
### Special rules
@@ -89,7 +92,6 @@ Build [configurable rules](./configurable-rules.md) if the rule you need isn't l
- [tag-description](./tag-description.md): Tags must have descriptions
- [tags-alphabetical](./tags-alphabetical.md): Tags in the top-level `tags` section must appear alphabetically
## Rule configuration syntax
To change your settings for any given rule, add or modify its corresponding entry in your Redocly configuration file.
@@ -128,6 +130,5 @@ rules:
## Next steps
* Learn more about [API linting](../api-standards.md), or follow the [guide to configuring a ruleset](../guides/configure-rules.md).
* If you didn't find the rule you need, build a [configurable rule](./configurable-rules.md) for a perfect linting fit.
- Learn more about [API linting](../api-standards.md), or follow the [guide to configuring a ruleset](../guides/configure-rules.md).
- If you didn't find the rule you need, build a [configurable rule](./configurable-rules.md) for a perfect linting fit.

4
docs/rules/component-name-unique.md
View File

@@ -1,3 +1,7 @@
---
slug: /docs/cli/rules/component-name-unique
---
# component-name-unique
Verifies component names are unique.

131
docs/rules/configurable-rules.md
View File

@@ -1,90 +1,92 @@
---
redirectFrom:
- /docs/cli/resources/rules/assertions/
- /docs/cli/rules/assertions/
- /docs/cli/rules/custom-rules/
redirects:
'/docs/cli/resources/rules/assertions/':
to: '/docs/cli/rules/configurable-rules/'
'/docs/cli/rules/assertions/':
to: '/docs/cli/rules/configurable-rules/'
'/docs/cli/rules/custom-rules/':
to: '/docs/cli/rules/configurable-rules/'
slug: /docs/cli/rules/configurable-rules
---
# Configurable rules
# Configurable rules
Configure flexible rules to meet any situation not covered by the [built-in rules](./built-in-rules.md) by adding to the `rules` map in the Redocly configuration file.
```yaml
rules:
rule/my-rule-name:
...
rule/one-more-rule-name:
...
rule/my-rule-name: ...
rule/one-more-rule-name: ...
```
A configurable rule describes the contents that the linter expects to find in your API description. During the validation process, the linter goes through your API description and checks if its contents match the expectations. If something was described in a configurable rule, but the API description doesn't correspond to the description, the linter shows you a warning or error message in the log.
Pattern Property | Type | Description
-- | -- | --
rule/{string} | [Configurable rule object](#configurable-rule-object) | Configurable rule definitions enforce your custom API design standards. Add or edit your configurable rules in the configuration file. A configurable rule is a rule that starts with a `rule/` prefix followed by a unique rule name. Rule names display in the lint log if the assertions fail. More than one configurable rule may be defined, and any configurable rule may have multiple assertions.
| Pattern Property | Type | Description |
| ---------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| rule/{string} | [Configurable rule object](#configurable-rule-object) | Configurable rule definitions enforce your custom API design standards. Add or edit your configurable rules in the configuration file. A configurable rule is a rule that starts with a `rule/` prefix followed by a unique rule name. Rule names display in the lint log if the assertions fail. More than one configurable rule may be defined, and any configurable rule may have multiple assertions. |
## Configurable rule object
Property | Type | Description
-- | -- | --
subject | [Subject object](#subject-object) | **REQUIRED.** Locates the specific [OpenAPI node type](#subject-node-types-and-properties) or `any` (see [example](#any-example)) and possible properties and values that the [lint command](../commands/lint.md) evaluates. Use with `where` to narrow further.
assertions | [Assertion object](#assertion-object) | **REQUIRED.** Flags a problem when a defined assertion evaluates false. There are a variety of built-in assertions included. You may also create plugins with custom functions and use them as assertions.
where | [Where object](#where-object) | Narrows subjects by evaluating the where list first in the order defined (from top to bottom). The resolution of reference objects is done at the `where` level. See [where example](#where-example). The `where` evaluation itself does not result in any problems.
message | string | Problem message displayed if the assertion is false. If omitted, the default message is: "{{assertionName}} failed because the {{subject}} {{property}} didn't meet the assertions: {{problems}}" is displayed. The available placeholders are displayed in that message. In the case there are multiple properties, the `{{property}}` placeholder produces a comma and space separate list of properties. In case there are multiple problems, the `{{problems}}` placeholder produces a bullet-list with a new line between each problem.
suggest | [string] | List of suggestions to display if the problem occurs.
severity | string | Configure the severity level of the problem if the assertion is false. It must be one of these values: `error`, `warn`, `off`. Default value is `error`.
| Property | Type | Description |
| ---------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| subject | [Subject object](#subject-object) | **REQUIRED.** Locates the specific [OpenAPI node type](#subject-node-types-and-properties) or `any` (see [example](#any-example)) and possible properties and values that the [lint command](../commands/lint.md) evaluates. Use with `where` to narrow further. |
| assertions | [Assertion object](#assertion-object) | **REQUIRED.** Flags a problem when a defined assertion evaluates false. There are a variety of built-in assertions included. You may also create plugins with custom functions and use them as assertions. |
| where | [Where object](#where-object) | Narrows subjects by evaluating the where list first in the order defined (from top to bottom). The resolution of reference objects is done at the `where` level. See [where example](#where-example). The `where` evaluation itself does not result in any problems. |
| message | string | Problem message displayed if the assertion is false. If omitted, the default message is: "{{assertionName}} failed because the {{subject}} {{property}} didn't meet the assertions: {{problems}}" is displayed. The available placeholders are displayed in that message. In the case there are multiple properties, the `{{property}}` placeholder produces a comma and space separate list of properties. In case there are multiple problems, the `{{problems}}` placeholder produces a bullet-list with a new line between each problem. |
| suggest | [string] | List of suggestions to display if the problem occurs. |
| severity | string | Configure the severity level of the problem if the assertion is false. It must be one of these values: `error`, `warn`, `off`. Default value is `error`. |
## Subject object
Property | Type | Description
-- | -- | --
type | string | **REQUIRED.** Locates the [OpenAPI node type](#subject-node-types-and-properties) that the [lint command](../commands/lint.md) evaluates.
property | string \| [string] \| null | Property name corresponding to the [OpenAPI node type](#subject-node-types-and-properties). If a list of properties is provided, assertions evaluate against each property in the sequence. If not provided (or null), assertions evaluate against the key names for the subject node type. See [property example](#property-example).
filterInParentKeys | [string] | The name of the subject's parent key that locates where assertions run. An example value given the subject `Operation` could be `filterInParentKeys: [get, put]` means that only `GET` and `PUT` operations are evaluated for the assertions. See [example](#mutuallyrequired-example).
filterOutParentKeys | [string] | The name of the subject's parent key that excludes where assertions run. An example value given the subject `Operation` could be `filterOutParentKeys: [delete]` means that all operations except `DELETE` operations are evaluated for the assertions.
matchParentKeys | string | Applies a regex pattern to the subject's parent keys to determine where assertions run. An example value given the subject `Operation` could be `matchParentKeys: /^p/` means that `POST`, `PUT`, and `PATCH` operations are evaluated for the assertions.
| Property | Type | Description |
| ------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | **REQUIRED.** Locates the [OpenAPI node type](#subject-node-types-and-properties) that the [lint command](../commands/lint.md) evaluates. |
| property | string \| [string] \| null | Property name corresponding to the [OpenAPI node type](#subject-node-types-and-properties). If a list of properties is provided, assertions evaluate against each property in the sequence. If not provided (or null), assertions evaluate against the key names for the subject node type. See [property example](#property-example). |
| filterInParentKeys | [string] | The name of the subject's parent key that locates where assertions run. An example value given the subject `Operation` could be `filterInParentKeys: [get, put]` means that only `GET` and `PUT` operations are evaluated for the assertions. See [example](#mutuallyrequired-example). |
| filterOutParentKeys | [string] | The name of the subject's parent key that excludes where assertions run. An example value given the subject `Operation` could be `filterOutParentKeys: [delete]` means that all operations except `DELETE` operations are evaluated for the assertions. |
| matchParentKeys | string | Applies a regex pattern to the subject's parent keys to determine where assertions run. An example value given the subject `Operation` could be `matchParentKeys: /^p/` means that `POST`, `PUT`, and `PATCH` operations are evaluated for the assertions. |
## Assertion object
A minimum of one assertion property is required to be defined.
Property | Type | Description
-- | -- | --
casing | string | Asserts a casing style. Supported styles are: `camelCase`, `kebab-case`, `snake_case`, `PascalCase`, `MACRO_CASE`, `COBOL-CASE`, `flatcase`. See [casing example](#casing-example).
const | string | Asserts equality of a value. The behavior is the same as the `enum` assertion with exactly one value. See [const example](#const-example).
defined | boolean | Asserts a property is defined. See [defined example](#defined-example).
disallowed | [string] | Asserts all listed values are not defined. See [disallowed example](#disallowed-example).
enum | [string] | Asserts a value is within a predefined list of values. Providing a single value in a list is an equality check. See [enum example](#enum-example).
maxLength | integer | Asserts a maximum length (exclusive) of a string or list (array). See [maxLength example](#maxlength-example).
minLength | integer | Asserts a minimum length (inclusive) of a string or list (array). See [minLength example](#minlength-example).
mutuallyExclusive | [string] | Asserts that listed properties (key names only) are mutually exclusive. See [mutuallyExclusive example](#mutuallyexclusive-example).
mutuallyRequired | [string] | Asserts that listed properties (key names only) are mutually required. See [mutuallyRequired example](#mutuallyrequired-example).
nonEmpty | boolean | Asserts a property is not empty. See [nonEmpty example](#nonempty-example).
notPattern | string | Asserts a value doesn't match a regex pattern. See [regex notPattern example](#notpattern-example).
pattern | string | Asserts a value matches a regex pattern. See [regex pattern example](#pattern-example).
ref | boolean \| string | Asserts a reference object presence in object's property. A boolean value of `true` means the property has a `$ref` defined. A boolean value of `false` means the property has not defined a `$ref` (it has an in-place value). A string value means that the `$ref` is defined and the unresolved value must match the pattern (for example, `'/paths\/. *\.yaml$/'`). See [ref example](#ref-example).|
required | [string] | Asserts all listed values are defined. See [required example](#required-example).
requireAny | [string] | Asserts that at least one of the listed properties (key names only) is defined. See [requireAny example](#requireany-example).
`{pluginId}/{functionName}` | object | Custom assertion defined in the plugin. This function is called with options including the value. See [custom function example](#custom-function-example).
| Property | Type | Description |
| --------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| casing | string | Asserts a casing style. Supported styles are: `camelCase`, `kebab-case`, `snake_case`, `PascalCase`, `MACRO_CASE`, `COBOL-CASE`, `flatcase`. See [casing example](#casing-example). |
| const | string | Asserts equality of a value. The behavior is the same as the `enum` assertion with exactly one value. See [const example](#const-example). |
| defined | boolean | Asserts a property is defined. See [defined example](#defined-example). |
| disallowed | [string] | Asserts all listed values are not defined. See [disallowed example](#disallowed-example). |
| enum | [string] | Asserts a value is within a predefined list of values. Providing a single value in a list is an equality check. See [enum example](#enum-example). |
| maxLength | integer | Asserts a maximum length (exclusive) of a string or list (array). See [maxLength example](#maxlength-example). |
| minLength | integer | Asserts a minimum length (inclusive) of a string or list (array). See [minLength example](#minlength-example). |
| mutuallyExclusive | [string] | Asserts that listed properties (key names only) are mutually exclusive. See [mutuallyExclusive example](#mutuallyexclusive-example). |
| mutuallyRequired | [string] | Asserts that listed properties (key names only) are mutually required. See [mutuallyRequired example](#mutuallyrequired-example). |
| nonEmpty | boolean | Asserts a property is not empty. See [nonEmpty example](#nonempty-example). |
| notPattern | string | Asserts a value doesn't match a regex pattern. See [regex notPattern example](#notpattern-example). |
| pattern | string | Asserts a value matches a regex pattern. See [regex pattern example](#pattern-example). |
| ref | boolean \| string | Asserts a reference object presence in object's property. A boolean value of `true` means the property has a `$ref` defined. A boolean value of `false` means the property has not defined a `$ref` (it has an in-place value). A string value means that the `$ref` is defined and the unresolved value must match the pattern (for example, `'/paths\/. *\.yaml$/'`). See [ref example](#ref-example). |
| required | [string] | Asserts all listed values are defined. See [required example](#required-example). |
| requireAny | [string] | Asserts that at least one of the listed properties (key names only) is defined. See [requireAny example](#requireany-example). |
| `{pluginId}/{functionName}` | object | Custom assertion defined in the plugin. This function is called with options including the value. See [custom function example](#custom-function-example). |
## Where object
The `where` object is part of a `where` list which must be defined in order from the root node.
Nodes may be skipped in between the subject node types of the where list and those defined in the root subject type.
Property | Type | Description
-- | -- | --
subject | [Subject object](#subject-object) | **REQUIRED.** Narrows the subject further.
assertions | [Assertion object](#assertion-object) | **REQUIRED.** Applies assertions to determine if the subject should continue towards evaluating the main assertions. If an assertion fails, it narrows that from downstream subject evaluation and does not report a problem.
| Property | Type | Description |
| ---------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| subject | [Subject object](#subject-object) | **REQUIRED.** Narrows the subject further. |
| assertions | [Assertion object](#assertion-object) | **REQUIRED.** Applies assertions to determine if the subject should continue towards evaluating the main assertions. If an assertion fails, it narrows that from downstream subject evaluation and does not report a problem. |
### `where` example
The following example asserts that PUT responses with HTTP status 200 or 201 cannot return an `application/pdf`content type.
Without the `where`, the assertion would evaluate every `MediaTypesMap` property including:
- Responses with all codes, including codes other than 200 or 201.
- Responses for all HTTP methods, including DELETE, GET, POST, and more.
To restrict the evaluation, use the `where` feature to limit what is evaluated.
To restrict the evaluation, use the `where` feature to limit what is evaluated.
```yaml
rule/no-pdf-in-ok-response:
@@ -132,11 +134,13 @@ rule/limit-is-integer:
The following example shows four assertions with multiple asserts in each one (`defined`, `minLength`, `maxLength`, `pattern`).
The `Operation`, `Tag`, and `Info` properties must:
- be defined
- have at least 30 characters
- end with a _full stop_.
In addition, the `Operation` summary property must:
- be defined
- be between 20 and 60 characters
- not end with a _full stop_.
@@ -196,11 +200,12 @@ In `plugin.js` each functions retrieves its options, checks for problems, and re
Each function is called with the following parameters:
Property | Type | Description
-- | -- | --
value | `string` \| [`string`] | Value that appears at the corresponding location.
options | `object` | Options that is described in the configuration file.
ctx | `object` | `ctx` object extends the [Context object](../custom-plugins/custom-rules.md#the-context-object) with two properties: `baseLocation`, and `rawValue`. Base location (`baseLocation`) contains the location in the source document for current assertion. (See [Location Object](../custom-plugins/custom-rules.md#location-object)). Raw value is the original assertion value.
| Property | Type | Description |
| -------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| value | `string` \| [`string`] | Value that appears at the corresponding location. |
| options | `object` | Options that is described in the configuration file. |
| ctx | `object` | `ctx` object extends the [Context object](../custom-plugins/custom-rules.md#the-context-object) with two properties: `baseLocation`, and `rawValue`. Base location (`baseLocation`) contains the location in the source document for current assertion. (See [Location Object](../custom-plugins/custom-rules.md#location-object)). Raw value is the original assertion value. |
**Return**
problems | [`Problem`] | List of problems. An empty list means all checks are valid.
@@ -211,6 +216,7 @@ message | `string` \| [`string`] | Problem message that is displayed in the [lin
location | `Location Object` | Location in the source document. See [Location Object](../custom-plugins/custom-rules.md#location-object)
`.redocly.yaml`
```yaml
rule/operation-summary-check:
subject:
@@ -232,7 +238,9 @@ rule/operation-summary-check:
local/checkWordsCount:
min: 3
```
`plugin.js`
```js
module.exports = {
id: 'local',
@@ -245,8 +253,8 @@ module.exports = {
return [
{
message: 'Operation summary should start with an active verb',
location: ctx.baseLocation
}
location: ctx.baseLocation,
},
];
},
checkWordsCount: (value, options, ctx) => {
@@ -257,8 +265,8 @@ module.exports = {
return [
{
message: `Operation summary should contain at least ${options.min} words`,
location: ctx.baseLocation
}
location: ctx.baseLocation,
},
];
},
},
@@ -281,6 +289,7 @@ rules:
```
Casing supports the following styles:
- camelCase
- COBOL-CASE
- flatcase
@@ -532,7 +541,6 @@ rules:
ref: /^(\.\/)?components\/.*\.yaml$/
```
### `required` example
The following example asserts that `PUT` requests have both `200` and `201` responses defined.
@@ -651,4 +659,3 @@ rules:
- name
- description
```

4
docs/rules/info-contact.md
View File

@@ -1,3 +1,7 @@
---
slug: /docs/cli/rules/info-contact
---
# info-contact
Requires the `Contact` info object defined in your API.

3
docs/rules/info-license-url.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/info-license-url
---
# info-license-url
Requires the license URL in your API descriptions.

3
docs/rules/info-license.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/info-license
---
# info-license
Requires the license info in your API descriptions.

3
docs/rules/minimal.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/minimal
---
# Minimal ruleset
The rules contained in the minimal ruleset:

3
docs/rules/no-ambiguous-paths.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/no-ambiguous-path
---
# no-ambiguous-paths
Ensures there are no ambiguous paths in your API descriptions.

3
docs/rules/no-empty-servers.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/np-empty-servers
---
# no-empty-servers
Requires the `servers` list is defined in your API.

4
docs/rules/no-enum-type-mismatch.md
View File

@@ -1,3 +1,7 @@
---
slug: /docs/cli/rules/no-enum-type-mismatch
---
# no-enum-type-mismatch
Requires that the contents of every `enum` value in your API description conform to the corresponding schema's specified `type`.

4
docs/rules/no-example-value-and-externalValue.md
View File

@@ -1,3 +1,7 @@
---
slug: /docs/cli/rules/no-example-value-and-externalValue
---
# no-example-value-and-externalValue
Ensures that `examples` object properties `externalValue` and `value` are mutually exclusive.

4
docs/rules/no-http-verbs-in-paths.md
View File

@@ -1,3 +1,7 @@
---
slug: /docs/cli/rules/no-http-verbs-in-paths
---
# no-http-verbs-in-paths
Disallows HTTP verbs used in paths.

3
docs/rules/no-identical-paths.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/no-identical-paths
---
# no-identical-paths
Ensures there are no identical paths in your API descriptions even when they have different path parameter names.

4
docs/rules/no-invalid-media-type-examples.md
View File

@@ -1,3 +1,7 @@
---
slug: /docs/cli/rules/no-invalid-media-type-examples
---
# no-invalid-media-type-examples
Disallow invalid media type examples by ensuring they comply with the corresponding schema definitions.

4
docs/rules/no-invalid-parameter-examples.md
View File

@@ -1,3 +1,7 @@
---
slug: /docs/cli/rules/no-invalid-parameter-examples
---
# no-invalid-parameter-examples
Disallow invalid parameter examples.

4
docs/rules/no-invalid-schema-examples.md
View File

@@ -1,3 +1,7 @@
---
slug: /docs/cli/rules/no-invalid-schema-examples
---
# no-invalid-schema-examples
Disallow invalid schema examples.

3
docs/rules/no-path-trailing-slash.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/no-path-trailing-slash
---
# no-path-trailing-slash
Ensures that paths in your API do not end with a trailing slash (`/`).

3
docs/rules/no-server-example-com.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/no-server-example-com
---
# no-server-example.com
Prevents using `example.com` as the value of the `servers.url` fields in your API descriptions.

3
docs/rules/no-server-trailing-slash.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/no-server-trailing-slash
---
# no-server-trailing-slash
Disallow servers with a trailing slash.

25
docs/rules/no-server-variables-empty-enum.md
View File

@@ -1,17 +1,19 @@
---
redirectFrom:
- /docs/cli/rules/no-empty-enum-servers/
redirects:
'/docs/cli/rules/no-empty-enum-servers/':
to: '/docs/cli/rules/no-server-variables-empty-enum/'
slug: /docs/cli/rules/no-server-variables-empty-enum
---
# no-server-variables-empty-enum
Disallow server variables without enum list defined.
|OAS|Compatibility|
|---|---|
|2.0|❌|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ❌ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -24,6 +26,7 @@ style ServerVariables fill:#codaf9,stroke:#0044d4,stroke-width:5px
## API design principles
If you use server variables, there are generally two kinds:
- tenant-driven
- environment-driven
@@ -31,9 +34,9 @@ In the case of environment-driven variables, you may want to predefine all of th
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `error` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------------------ |
| severity | string | Possible values: `off`, `warn`, `error`. Default `error` (in `recommended` configuration). |
An example configuration:

3
docs/rules/no-undefined-server-variable.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/no-undefined-server-variable
---
# no-undefined-server-variable
Disallow undefined server variables.

3
docs/rules/no-unresolved-refs.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/no-unresolved
---
# no-unresolved-refs
Ensures that all `$ref` instances in your API descriptions are resolved.

3
docs/rules/no-unused-components.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/no-unused-components
---
# no-unused-components
Ensures that every component specified in your API description is used at least once.

4
docs/rules/operation-2xx-response.md
View File

@@ -1,3 +1,7 @@
---
slug: /docs/cli/rules/operation-2xx-response
---
# operation-2xx-response
Ensures that every operation in your API document has at least one successful (200-299) HTTP response defined.

3
docs/rules/operation-4xx-problem-details-rfc7807.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/operation-4xx-problem-details-rfc7807
---
# operation-4xx-problem-details-rfc7807
Ensures that every operation with (400-499) HTTP response has content-type `application/problem+json` and fields `title` and `type`.

4
docs/rules/operation-4xx-response.md
View File

@@ -1,3 +1,7 @@
---
slug: /docs/cli/rules/operation-4xx-response
---
# operation-4xx-response
Ensures that every operation in your API document has at least one error (400-499) HTTP response defined.

3
docs/rules/operation-description.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/operation-description
---
# operation-description
Requires the `description` field for every operation in your API.

3
docs/rules/operation-operationId-unique.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/operation-operationId-unique
---
# operation-operationId-unique
Requires unique `operationId` values for each operation.

3
docs/rules/operation-operationId-url-safe.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/operation-operationId-url-safe
---
# operation-operationId-url-safe
Requires the `operationId` value to be URL safe.

3
docs/rules/operation-operationId.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/operation-operationId
---
# operation-operationId
Requires each operation to have an `operationId` defined.

3
docs/rules/operation-parameters-unique.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/operation-parameters-unique
---
# operation-parameters-unique
Verifies parameters are unique for any given operation.

3
docs/rules/operation-singular-tag.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/operation-singular-tag
---
# operation-singular-tag
Disallows multiple tags for an operation.

3
docs/rules/operation-summary.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/operation-summary
---
# operation-summary
Enforce that every operation has a summary.

3
docs/rules/operation-tag-defined.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/operation-tag-defined
---
# operation-tag-defined
Disallows use of tags in operations that aren't globally defined.

3
docs/rules/parameter-description.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/parameter-description
---
# parameter-description
Ensure that every parameter has a description.

3
docs/rules/path-declaration-must-exist.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/path-declaration-must-exist
---
# path-declaration-must-exist
Requires definition of all path template variables.

3
docs/rules/path-excludes-patterns.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/path-excludes-patterns
---
# path-excludes-patterns
Disallow patterns from paths.

3
docs/rules/path-not-include-query.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/path-not-include-query
---
# path-not-include-query
Path should not include query parameters.

3
docs/rules/path-parameters-defined.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/path-parameters-defined
---
# path-parameters-defined
Requires all path template variables are defined as path parameters.

3
docs/rules/path-segment-plural.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/path-segment-plural
---
# path-segment-plural
Enforces plural path segments.

3
docs/rules/paths-kebab-case.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/paths-kebab-case
---
# paths-kebab-case
Require kebab-case in paths instead of camelCase or snake_case.

3
docs/rules/recommended.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/recommended
---
# Recommended ruleset
These are the rules in the `recommended` set, grouped by their severity.

3
docs/rules/request-mime-type.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/request-mine-type
---
# request-mime-type
|OAS|Compatibility|

3
docs/rules/required-string-property-missing-min-length.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/required-string-property-missing-min-length
---
# required-string-property-missing-min-length
Requires that every required property in the API description with type `string` has a `minLength`.

3
docs/rules/response-contains-header.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/response-contains-header
---
# response-contains-header
Requires that response objects with specific HTTP status codes or ranges contain specified response headers.

3
docs/rules/response-contains-property.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/response-contains-property
---
# response-contains-property
Enforces definition of specific response properties based on HTTP status code or HTTP status code range. A specific status code takes priority over the status code range.

3
docs/rules/response-mime-type.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/response-mime-type
---
# response-mime-type
|OAS|Compatibility|

3
docs/rules/scalar-property-missing-example.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/scalar-property-missing-example
---
# scalar-property-missing-example
Requires that every scalar property in the API description has either `example` or `examples`˙ defined.

3
docs/rules/security-defined.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/security-defined
---
# security-defined
Verifies every operation or global security is defined.

1
docs/rules/sidebars.yaml
View File

@@ -1 +0,0 @@
- page: ./*

3
docs/rules/spec-components-invalid-map-name.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/spec-components-invalid-map-name
---
# spec-components-invalid-map-name
Requires that specific objects inside `components` MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.

3
docs/rules/spec-strict-refs.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/spec-strict-refs
---
# spec-strict-refs
Checks that `$ref` is only used in the locations permitted by the OpenAPI specification.

3
docs/rules/spec.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/spec
---
# spec
Ensures that your API document conforms to the [OpenAPI specification](https://spec.openapis.org/oas/v3.1.0.html).

3
docs/rules/tag-description.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/tag-description
---
# tag-description
Requires that the tags all have a non-empty `description`.

3
docs/rules/tags-alphabetical.md
View File

@@ -1,3 +1,6 @@
---
slug: /docs/cli/rules/tags-alphabetical
---
# tags-alphabetical
Ensures that all tag `name` fields in the `tags` object are listed in alphabetical order.