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

chore: Run prettier on all docs files (#1334)

Browse Source
This commit is contained in:
Lorna Jane Mitchell
2023-11-17 09:45:03 +00:00
committed by GitHub
parent 166e16d6ca
commit de80612b55
83 changed files with 792 additions and 743 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.prettierrc.json
View File

@@ -1,4 +1,5 @@
{
"printWidth": 100,
"singleQuote": true
"singleQuote": true,
"embeddedLanguageFormatting": "off"
}

17
docs/api-docs.md
View File

@@ -17,10 +17,10 @@ This option is ideal for teams that want **hassle-free hosting**, lots of **them
Get started with Redocly API reference:
* [Sign up for Workflows](https://app.redocly.com/signup) and add your OpenAPI description to the registry to get started immediately.
* Check out the [documentation for using the API registry](https://redocly.com/docs/api-registry/guides/api-registry-quickstart/) to learn more.
* Use Redocly CLI for [local preview of API documentation](./commands/preview-docs.md) while you're making changes to the API description or docs configuration.
* Add the [Redocly VS Code extension](https://redocly.com/docs/redocly-openapi/) to your IDE for better OpenAPI editing support and autocomplete on Redocly configuration settings.
- [Sign up for Workflows](https://app.redocly.com/signup) and add your OpenAPI description to the registry to get started immediately.
- Check out the [documentation for using the API registry](https://redocly.com/docs/api-registry/guides/api-registry-quickstart/) to learn more.
- Use Redocly CLI for [local preview of API documentation](./commands/preview-docs.md) while you're making changes to the API description or docs configuration.
- Add the [Redocly VS Code extension](https://redocly.com/docs/redocly-openapi/) to your IDE for better OpenAPI editing support and autocomplete on Redocly configuration settings.
## Redoc
@@ -32,8 +32,7 @@ Use this option if you plan to host your API reference documentation yourself, o
Get started with Redoc:
* Visit the [Redoc section of the docs](https://redocly.com/docs/redoc/quickstart/) to learn more about redoc
* Check out the project and community [on GitHub](https://github.com/redocly/redoc).
* Use Redocly CLI for [local preview of API documentation](./commands/preview-docs.md) while you're making changes to the API description or docs configuration, and to [build your API docs](./commands/build-docs.md).
* Add the [Redocly VS Code extension](https://redocly.com/docs/redocly-openapi/) to your IDE for better OpenAPI editing support and autocomplete on Redocly configuration settings.
- Visit the [Redoc section of the docs](https://redocly.com/docs/redoc/quickstart/) to learn more about redoc
- Check out the project and community [on GitHub](https://github.com/redocly/redoc).
- Use Redocly CLI for [local preview of API documentation](./commands/preview-docs.md) while you're making changes to the API description or docs configuration, and to [build your API docs](./commands/build-docs.md).
- Add the [Redocly VS Code extension](https://redocly.com/docs/redocly-openapi/) to your IDE for better OpenAPI editing support and autocomplete on Redocly configuration settings.

6
docs/api-standards.md
View File

@@ -17,9 +17,9 @@ Choose between one of the existing rulesets, or compile your own. There are some
Once the ruleset is created, use it with your API and Redocly in any or all of these ways:
* every update to an API in the API registry is linted with the rules for that API
* use Redocly CLI to lint APIs as part of your continuous integration setup, such as in GitHub Actions
* during development, check the API you are working on using Redocly CLI on your local machine
- every update to an API in the API registry is linted with the rules for that API
- use Redocly CLI to lint APIs as part of your continuous integration setup, such as in GitHub Actions
- during development, check the API you are working on using Redocly CLI on your local machine
By establishing good standards and making them part of your development workflow, keeping the APIs as you would like them becomes painless good practice, even when there are many changes being worked on.

10
docs/changelog.md
View File

@@ -3,7 +3,6 @@ toc:
maxDepth: 2
---
# Redocly CLI changelog
<!-- do-not-remove -->
@@ -164,7 +163,7 @@ No code changes.
### Features
- Resolve `$ref`s in preprocessors.
- Create the `spec-strict-refs` rule to ensure `$ref` usage is in accordance with the OpenAPI specification.
- Create the `spec-strict-refs` rule to ensure `$ref` usage is in accordance with the OpenAPI specification.
### Fixes
@@ -210,7 +209,6 @@ No code changes.
- Stopped executing decorators and preprocessors upon the `join` command.
- Sort top-level OAS3 keys in `bundle` and `join` commands.
## 1.0.0-beta.125 (2023-04-06)
### Features
@@ -260,12 +258,14 @@ No code changes.
- Moved and renamed the `features.openapi` and `features.mockServer` into the `theme` object with the names `openapi` and `mockServer`.
Before:
```yaml
features.openapi: {}
features.mockServer: {}
```
After:
```yaml
theme:
openapi: {}
@@ -383,6 +383,7 @@ theme:
- Fixed incorrect behavior for the `no-invalid-media-type-examples` rule in combination with the `allOf` keyword.
## 1.0.0-beta.109 (2022-09-08)
### Features
- Added rfc7807 problem details rule.
@@ -390,7 +391,6 @@ theme:
- Added the [`spec-components-invalid-map-name`](./rules/spec-components-invalid-map-name.md) rule for component map names validation.
- Added a new lint `--format` option: `summary`.
### Fixes
- Fixed an issue with multi-line strings in literal mode.
@@ -423,7 +423,6 @@ theme:
- Fixed docs for `no-server-example.com`.
- Incorrect schema description dereferenced.
## 1.0.0-beta.107 (2022-08-16)
### Changes
@@ -434,7 +433,6 @@ theme:
- Introduced severity level `off` for assertions.
## 1.0.0-beta.106 (2022-08-09)
### Fixes

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

@@ -27,7 +27,7 @@ redocly build-docs <api> -t custom.hbs --templateOptions.metaDescription "Page m
| --template, -t | string | Uses custom [Handlebars](https://handlebarsjs.com/) templates to render your OpenAPI description. |
| --templateOptions | string | Adds template options you want to pass to your custom Handlebars template. To add options, use dot notation. |
| --theme.openapi | string | Customizes your output with [Redoc functionality options](https://redocly.com/docs/api-reference-docs/configuration/functionality/) or [Redoc theming options](https://redocly.com/docs/api-reference-docs/configuration/theming/). |
| --title | string | Sets the page title. |
| --title | string | Sets the page title. |
| --version | boolean | Shows version number. |
## Examples

62
docs/commands/lint.md
View File

@@ -22,19 +22,19 @@ redocly lint --version
## Options
| Option | Type | Description |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Option | Type | Description |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| apis | [string] | Array of API description filenames that need to be linted. See [the Apis section](#apis) for more options. |
| --config | string | Specify path to the [configuration file](#custom-configuration-file). |
| --extends | [string] | [Extend a specific configuration](#extend-configuration) (defaults or config file settings). |
| --config | string | Specify path to the [configuration file](#custom-configuration-file). |
| --extends | [string] | [Extend a specific configuration](#extend-configuration) (defaults or config file settings). |
| --format | string | Format for the output.<br />**Possible values:** `codeframe`, `stylish`, `json`, `checkstyle`, `codeclimate`, `summary`. Default value is `codeframe`. |
| --generate-ignore-file | boolean | [Generate ignore file](#generate-ignore-file). |
| --help | boolean | Show help. |
| --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
| --max-problems | integer | Truncate output to display the specified [maximum number of problems](#max-problems). Default value is 100. |
| --skip-preprocessor | [string] | Ignore certain preprocessors. See the [Skip preprocessor or rule section](#skip-preprocessor-or-rule) below. |
| --skip-rule | [string] | Ignore certain rules. See the [Skip preprocessor or rule section](#skip-preprocessor-or-rule) below. |
| --version | boolean | Show version number. |
| --generate-ignore-file | boolean | [Generate ignore file](#generate-ignore-file). |
| --help | boolean | Show help. |
| --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
| --max-problems | integer | Truncate output to display the specified [maximum number of problems](#max-problems). Default value is 100. |
| --skip-preprocessor | [string] | Ignore certain preprocessors. See the [Skip preprocessor or rule section](#skip-preprocessor-or-rule) below. |
| --skip-rule | [string] | Ignore certain rules. See the [Skip preprocessor or rule section](#skip-preprocessor-or-rule) below. |
| --version | boolean | Show version number. |
## Examples
@@ -57,16 +57,20 @@ The `apis` argument can also use any glob format supported by your file system.
Instead of full paths, you can use names listed in the `apis` section of your Redocly configuration file.
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint core@v1
```
{% /tab %}
{% tab label="Configuration file" %}
```yaml
apis:
core@v1:
root: ./openapi/api-description.json
```
{% /tab %}
{% /tabs %}
@@ -77,11 +81,14 @@ In this case, after resolving the path behind the `core@v1` name (see the `Confi
You can omit apis completely when executing the `lint` command to check all APIs defined in the configuration file.
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint
```
{% /tab %}
{% tab label="Configuration file" %}
```yaml
apis:
core@v1:
@@ -91,6 +98,7 @@ 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.
@@ -125,14 +133,18 @@ Some formats, such as CheckStyle or JSON, don't work well when mulitple APIs are
{% /admonition %}
#### Codeframe (default)
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint --format=codeframe
## equivalent to: redocly lint
```
{% /tab %}
{% tab label="Output" %}
```bash
[1] resources/petstore-with-errors.yaml:16:3 at #/paths/~1pets?id
@@ -147,6 +159,7 @@ 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`.
@@ -154,19 +167,24 @@ Note that the problems are displayed in the following format: `file:line:column`
Depending on the terminal emulator you use, it may be possible to directly click this indicator to edit the file in place.
#### Stylish
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint --format=stylish
```
{% /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.
@@ -176,11 +194,14 @@ In this format, `lint` shows the file name, line number, and column where the pr
It can be useful to get the output in JSON format to be processed by other tools.
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint --format=json
```
{% /tab %}
{% tab label="Output" %}
```bash
{
"totals": {
@@ -223,18 +244,23 @@ redocly lint --format=json
]
}
```
{% /tab %}
{% /tabs %}
#### Checkstyle
The `lint` command also supports the [Checkstyle](https://checkstyle.org/) XML report format.
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint --format=checkstyle
```
{% /tab %}
{% tab label="Output" %}
```bash
<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="4.3">
@@ -245,6 +271,7 @@ redocly lint --format=checkstyle
</file>
</checkstyle>
```
{% /tab %}
{% /tabs %}
Due to the limitations of this format, only file name, line, column, severity,
@@ -256,17 +283,22 @@ omitted.
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.
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint --max-problems 200
```
{% /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.
@@ -274,15 +306,19 @@ With this option, you can generate the `.redocly.lint-ignore.yaml` file to suppr
This option is useful when you have an API design standard, but have some exceptions to the rule (for example, a legacy API operation). It allows for highly granular control.
{% tabs %}
{% tab label="Command" %}
```shell
redocly lint openapi/petstore.yaml --generate-ignore-file
```
{% /tab %}
{% tab label="Output" %}
```bash
...
Generated ignore file with 3 problems.
```
{% /tab %}
{% /tabs %}
@@ -316,14 +352,18 @@ The rule in the example is named `spec`, which indicates compliance with the Ope
You may want to skip specific preprocessors or rules upon running the command.
{% tabs %}
{% tab label="Skip preprocessors" %}
```bash
redocly lint --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example
```
{% /tab %}
{% tab label="Skip rules" %}
```bash
redocly lint --skip-rule=no-sibling-refs --skip-rule=no-parent-tags
```
{% /tab %}
{% /tabs %}

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

@@ -2,11 +2,10 @@
You can bundle configurations under the `configs` key in your plugin code. These configuration bundles are
useful when you declare multiple rules or decorators in your plugin, and you want to
define within the plugin how to combine them. Each plugin can have multiple
define within the plugin how to combine them. Each plugin can have multiple
configuration bundles, and the user can use any of them in their `redocly.yaml`
configuration file.
The following is an example plugin, defining two configuration bundles:
```js
@@ -46,4 +45,3 @@ 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 %}

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

@@ -2,8 +2,8 @@
Decorators transform API descriptions, by adding, removing, or changing elements of the document. Before you build your own decorators:
* [Learn about Redocly decorators](../decorators.md).
* [Check the list of built-in decorators](../decorators.md#list-of-decorators).
- [Learn about Redocly decorators](../decorators.md).
- [Check the list of built-in decorators](../decorators.md#list-of-decorators).
If you can't find an existing decorator that fits your needs, then you can add a decorator in a plugin.
@@ -146,6 +146,7 @@ With this configuration, an `operationId` called `GetAllItems` would be rewritte
## Further examples of custom decorators
See some more examples of decorators:
- Follow our [replace-servers-url tutorial](../guides/replace-servers-url.md).
- Change your [OAuth2 token URL](../guides/change-token-url.md).

8
docs/custom-plugins/custom-rules.md
View File

@@ -2,9 +2,9 @@
Rules are used to make sure that the API description is in the expected format and aligns with the expected API standards. Before you build any custom rules:
* Learn more about [Redocly rules](../rules.md).
* Check the list of [built-in rules](../rules/built-in-rules.md).
* See if you can build a [configurable rule](../rules/configurable-rules.md) to meet your needs.
- Learn more about [Redocly rules](../rules.md).
- Check the list of [built-in rules](../rules/built-in-rules.md).
- See if you can build a [configurable rule](../rules/configurable-rules.md) to meet your needs.
Exhaust the above options first, because they are simpler and more maintainable than building a custom plugin. If you need to build your own rules though, then you're in the right place! Read on ...
@@ -99,7 +99,6 @@ context.report({
By default, the message is reported at the current node location.
### Location object
The Location class has the following fields:
@@ -114,4 +113,3 @@ and the following methods:
- `child(propName)` - Returns the new Location pointing to the `propName` of the current node. `propName` can be an array of strings to point deep.
You can use this information for more granular rule definitions.

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

@@ -69,5 +69,3 @@ module.exports = {
Everything that is exported from a plugin relates to one of the supported document formats, such as OpenAPI v3. Plugins work by exporting an object containing a key-value mapping from a document format and version (`oas2` or `oas3` are supported) to an extension object (rules, preprocessors, decorators).
Before processing the API description document, Redocly CLI detects the document format and applies a corresponding set of extensions.

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

@@ -4,7 +4,6 @@ _Visitor_ is a design pattern that allows operations to be performed on individu
To understand how this applies to your API description, think of the document as a tree structure. The top level elements are entries like `info` and `components`. To examine the `description` field in the `info` section, the visitor goes to the `info` node first, then on to the `description` node. This pattern is repeated all over the document as the visitor pattern works its way around the document tree.
## Structure of the visitor object
In your plugin, create a JavaScript visitor object, and describe the functionality required for each type of node.
@@ -12,7 +11,6 @@ In your plugin, create a JavaScript visitor object, and describe the functionali
Redocly CLI calls `enter()` while going down the tree and `leave()` going up the tree after processing the node and its children.
If the `skip()` predicate is defined and returns `true` the node is ignored for this visitor.
```js
function ExampleRule() {
const seen = {};
@@ -37,7 +35,6 @@ Keys of the object are one of the following:
- `any` - visitor is called on every node.
- `ref` - visitor is called on $ref nodes.
## Visitors execution and $ref
Top level **visitor functions** run only once for each node.
@@ -108,5 +105,3 @@ type string from getOp
type object from getOp
type number from putOp
```

11
docs/decorators/filter-in.md
View File

@@ -8,12 +8,11 @@ Giant monolithic API docs can overwhelm anyone. By filtering what is most releva
## Configuration
|Option|Type|Description|
|---|---|---|
|property|string|**REQUIRED.** The property name used for evaluation. It attempts to match the values.|
|value|[string]|**REQUIRED.** List of values used for the matching.|
|matchStrategy|string|Possible values: `all`, `any`. If `all` it needs to match all of the values supplied. If `any` it needs to match only one of the values supplied. Default value: `any`.|
| Option | Type | Description |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| property | string | **REQUIRED.** The property name used for evaluation. It attempts to match the values. |
| value | [string] | **REQUIRED.** List of values used for the matching. |
| matchStrategy | string | Possible values: `all`, `any`. If `all` it needs to match all of the values supplied. If `any` it needs to match only one of the values supplied. Default value: `any`. |
Example of configuration:

10
docs/decorators/filter-out.md
View File

@@ -9,11 +9,11 @@ Giant monolithic API docs can overwhelm anyone. By filtering what is most releva
## Configuration
|Option|Type|Description|
|---|---|---|
|property|string|**REQUIRED.** The property name used for evaluation. It attempts to match the values.|
|value|[string]|**REQUIRED.** List of values used for the matching.|
|matchStrategy|string|Possible values: `all`, `any`. If `all` it needs to match all of the values supplied. If `any` it needs to match only one of the values supplied. Default value: `any`.|
| Option | Type | Description |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| property | string | **REQUIRED.** The property name used for evaluation. It attempts to match the values. |
| value | [string] | **REQUIRED.** List of values used for the matching. |
| matchStrategy | string | Possible values: `all`, `any`. If `all` it needs to match all of the values supplied. If `any` it needs to match only one of the values supplied. Default value: `any`. |
Example of configuration:

8
docs/decorators/info-description-override.md
View File

@@ -8,12 +8,11 @@ Sometimes developers generate OpenAPI and the descriptions need to be improved a
This generally happens when you don't have permission to edit the source.
This decorator provides a way to "overlay" a new description over the source, so that as the source changes, the modifications can be reapplied.
## Configuration
|Option|Type|Description|
|---|---|---|
|filePath|string|**REQUIRED.** The relative path to a Markdown file containing the desired info description.|
| Option | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------------------- |
| filePath | string | **REQUIRED.** The relative path to a Markdown file containing the desired info description. |
Example of a configuration:
@@ -27,7 +26,6 @@ decorators:
![info-description-override](https://user-images.githubusercontent.com/1161871/140232772-502fe663-8af7-4da6-a345-21b8067129bc.png)
See a repository with [info, operation, and tag description overrides](https://github.com/redocly-demo/decorators-demo).
## Related decorators

7
docs/decorators/info-override.md
View File

@@ -8,12 +8,11 @@ Sometimes developers generate OpenAPI and the info object need to be improved af
This generally happens when you have no permission to edit the source.
This decorator provides a way to "overlay" a new info section over the source so that as the source changes, the modifications can be reapplied.
## Configuration
|Option|Type|Description|
|---|---|---|
|_additionalProperties_|any|**REQUIRED.** Any properties from the OpenAPI info object.|
| Option | Type | Description |
| ---------------------- | ---- | ---------------------------------------------------------- |
| _additionalProperties_ | any | **REQUIRED.** Any properties from the OpenAPI info object. |
Example of a configuration:

7
docs/decorators/media-type-examples-override.md
View File

@@ -10,9 +10,9 @@ This decorator provides a way to "overlay" a new examples over the source so tha
## Configuration
|Option|Type| Description |
|---|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
|operationIds|object| **REQUIRED.** Object consisting of operationIds as keys, and object as a value that containing the request and responses keys and example`s paths as values. |
| Option | Type | Description |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| operationIds | object | **REQUIRED.** Object consisting of operationIds as keys, and object as a value that containing the request and responses keys and example`s paths as values. |
Example of a configuration:
@@ -96,6 +96,7 @@ paths:
value:
name: example
```
## Related decorators
- [operation-description-override](./operation-description-override.md)

8
docs/decorators/operation-description-override.md
View File

@@ -8,12 +8,11 @@ Sometimes developers generate OpenAPI and the descriptions need to be improved a
This generally happens when you have no permission to edit the source.
This decorator provides a way to "overlay" a new description over the source so that as the source changes, the modification can be reapplied
## Configuration
|Option|Type|Description|
|---|---|---|
|operationIds|object|**REQUIRED.** List of key values pairs with operationIds as the key and paths to Markdown files as the value.|
| Option | Type | Description |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------- |
| operationIds | object | **REQUIRED.** List of key values pairs with operationIds as the key and paths to Markdown files as the value. |
Example of a configuration:
@@ -29,7 +28,6 @@ decorators:
![operation-description-override](https://user-images.githubusercontent.com/1161871/140233186-50d4cf13-46bc-4414-8231-35f87179825e.png)
See a repository with [info, operation, and tag description overrides](https://github.com/redocly-demo/decorators-demo).
## Related decorators

6
docs/decorators/remove-x-internal.md
View File

@@ -10,9 +10,9 @@ This is a mechanism that can be used to maintain them together but generate two
## Configuration
|Option|Type|Description|
|---|---|---|
|internalFlagProperty|string|The property name used for evaluation. Default value: `x-internal`|
| Option | Type | Description |
| -------------------- | ------ | ------------------------------------------------------------------ |
| internalFlagProperty | string | The property name used for evaluation. Default value: `x-internal` |
Example of a configuration that uses `x-internal` as the flag property:

8
docs/decorators/tag-description-override.md
View File

@@ -8,12 +8,11 @@ Sometimes developers generate OpenAPI and the descriptions need to be improved a
This generally happens when you have no permission to edit the source.
This decorator provides a way to "overlay" a new description over the source so that as the source changes, the modifications can be reapplied.
## Configuration
|Option|Type|Description|
|---|---|---|
|tagNames|object|**REQUIRED.** List of key values pairs with tag names as the key and paths to Markdown files as the value.|
| Option | Type | Description |
| -------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| tagNames | object | **REQUIRED.** List of key values pairs with tag names as the key and paths to Markdown files as the value. |
Example of a configuration:
@@ -29,7 +28,6 @@ decorators:
![tag-description-override](https://user-images.githubusercontent.com/1161871/140233049-e36a1bcc-4267-41b8-b646-6159a282d54a.png)
See a repository with [info, operation, and tag description overrides](https://github.com/redocly-demo/decorators-demo).
## Related decorators

12
docs/file-management.md
View File

@@ -18,9 +18,10 @@ redocly split openapi.yaml --outDir myApi
```
The original file is unchanged, but look in the directory named by the `--outDir` parameter. It now contains:
* An `openapi.yaml` file, which is the entry point of the API and includes the `info` section and other metadata. This file also contains the bare bones of the API description, with all the details moved to dedicated files.
* A `paths/` directory, with a file for each of the URLs in the API. All verbs for that endpoint are in this file.
* A `components/` directory containing subdirectories for each of the top-level keys, such as `schema`, and files for the individual data structures described in each section.
- An `openapi.yaml` file, which is the entry point of the API and includes the `info` section and other metadata. This file also contains the bare bones of the API description, with all the details moved to dedicated files.
- A `paths/` directory, with a file for each of the URLs in the API. All verbs for that endpoint are in this file.
- A `components/` directory containing subdirectories for each of the top-level keys, such as `schema`, and files for the individual data structures described in each section.
By keeping your API in this format, managing changes can be easier since it's clear which file (or files) have changed, making it easier to review as things change. Many common operations can be performed on the API description in this format, such as linting. Some tools prefer a single bundled OpenAPI description, and it's common to bundle during CI (continuous integration) before doing other automated operations.
@@ -70,6 +71,5 @@ Gives a summary of the API, including the number of operations, tags, schemas, a
## Further reading
* See [all Redocly CLI commands](./commands/index.md)
* Learn how to [filter out internal API endpoints before publishing](./guides/hide-apis.md) if you have more detailed API descriptions than you want to pass to another stage of the API workflow
- See [all Redocly CLI commands](./commands/index.md)
- Learn how to [filter out internal API endpoints before publishing](./guides/hide-apis.md) if you have more detailed API descriptions than you want to pass to another stage of the API workflow

2
docs/guides/autocomplete.md
View File

@@ -7,6 +7,7 @@ Generation the completion script:
```shell Command
redocly completion
```
The command output contains installation instructions. For example, to install the completion script in `bash`, use:
```shell Command
@@ -14,4 +15,3 @@ redocly completion >> ~/.bashrc
```
The approach is similar for other shells. After the installation, restart your terminal for the changes to take effect.

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

@@ -7,8 +7,9 @@ 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).
{% tabs %}
{% tab label="redocly.yaml" %}
{% tabs %}
{% tab label="redocly.yaml" %}
```yaml
extends:
- recommended
@@ -18,8 +19,10 @@ Estimated time: 15 minutes
plugin/change-token-url:
tokenUrl: 'https://token.example.com/url'
```
{% /tab %}
{% tab label="acme-plugin.js" %}
{% /tab %}
{% tab label="acme-plugin.js" %}
```js
const ChangeTokenUrl = require('./decorators/change-token-url');
const id = 'plugin';
@@ -36,8 +39,10 @@ Estimated time: 15 minutes
decorators,
};
```
{% /tab %}
{% tab label="decorators/change-token-url.js" %}
{% /tab %}
{% tab label="decorators/change-token-url.js" %}
```js
module.exports = ChangeTokenUrl;
@@ -54,5 +59,6 @@ Estimated time: 15 minutes
};
}
```
{% /tab %}
{% /tabs %}
{% /tab %}
{% /tabs %}

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

@@ -11,9 +11,9 @@ In this guide, learn how to choose and adapt the rules built into Redocly for yo
To get started, try one of the existing rulesets and see if it meets your needs.
* The [`recommended`](../rules/recommended.md) ruleset has a good basic set of rules for a consistent, user-friendly API.
* The [recommended-strict](../rules/recommended.md#recommended-strict-ruleset) ruleset is identical to the `recommended`, except it elevates all warnings to errors so that you don't miss the warnings, i.e. in a CI pipeline.
* Or try the [`minimal`](../rules/minimal.md) ruleset which shows some warnings, but far fewer errors that would cause the lint to fail.
- The [`recommended`](../rules/recommended.md) ruleset has a good basic set of rules for a consistent, user-friendly API.
- The [recommended-strict](../rules/recommended.md#recommended-strict-ruleset) ruleset is identical to the `recommended`, except it elevates all warnings to errors so that you don't miss the warnings, i.e. in a CI pipeline.
- Or try the [`minimal`](../rules/minimal.md) ruleset which shows some warnings, but far fewer errors that would cause the lint to fail.
You can specify the ruleset with the `lint` command in Redocly CLI like this:
@@ -147,13 +147,14 @@ apis:
```
There's a few things going on in the example, but let's look at each feature in turn:
* The first section configures `recommended` as the default ruleset for all APIs. The "newsletter" API overrides this by declaring `minimal` for itself, but the others inherit the top-level setting.
* No rules are defined at the top level, but since every API sets the `no-server-trailing-slash` rule to "off", this could be set at the top level.
* Each API adds (or removes) the rules that fit their use case, including using the `version-semver` assertion.
- The first section configures `recommended` as the default ruleset for all APIs. The "newsletter" API overrides this by declaring `minimal` for itself, but the others inherit the top-level setting.
- No rules are defined at the top level, but since every API sets the `no-server-trailing-slash` rule to "off", this could be set at the top level.
- Each API adds (or removes) the rules that fit their use case, including using the `version-semver` assertion.
Configuring per-API means that there doesn't have to be compromise for the lowest standard that all APIs can meet. Especially when you are working on improving your APIs or API descriptions, setting the desired ruleset and adding exceptions until the API meets all requirements in full is a good way to ensure standards only improve.
## Next steps
* Check out the detailed reference documentation for the [built-in rules](../rules/built-in-rules.md) and [configurable rules](../rules/configurable-rules.md).
* If nothing there meets your needs, you can create your own rules by creating [custom plugins](../custom-plugins/index.md) with JavaScript.
- Check out the detailed reference documentation for the [built-in rules](../rules/built-in-rules.md) and [configurable rules](../rules/configurable-rules.md).
- If nothing there meets your needs, you can create your own rules by creating [custom plugins](../custom-plugins/index.md) with JavaScript.

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

@@ -34,21 +34,21 @@ In this step, create a custom plugin and define the decorator dependency.
1. Create a new directory called `plugins`.
1. In the `plugins` directory, create a `plugin.js` file with the following code:
```js
const hideOpenapiExtensions = require('./decorators/hide-openapi-extensions');
const id = 'plugin';
```js
const hideOpenapiExtensions = require('./decorators/hide-openapi-extensions');
const id = 'plugin';
const decorators = {
oas3: {
'hide-openapi-extensions': hideOpenapiExtensions,
},
};
const decorators = {
oas3: {
'hide-openapi-extensions': hideOpenapiExtensions,
},
};
module.exports = {
id,
decorators,
};
```
module.exports = {
id,
decorators,
};
```
1. Save the file.
@@ -61,28 +61,28 @@ You can name the plugins directory and the file anything you want. Make sure you
1. In the `plugins` directory, create a new directory called `decorators`.
1. In the `decorators` directory, create a `hide-openapi-extensions.js` file with the following code:
```js
module.exports = hideOpenapiExtensions;
```js
module.exports = hideOpenapiExtensions;
/** @type {import('@redocly/cli').OasDecorator} */
/** @type {import('@redocly/cli').OasDecorator} */
function hideOpenapiExtensions({ pattern }) {
return {
any: {
enter: node => {
pattern.forEach(item => {
Object.keys(node).forEach(key => {
const regex = new RegExp(item, 'i');
if (regex.test(key)) {
delete node[key];
}
});
});
}
}
}
}
```
function hideOpenapiExtensions({ pattern }) {
return {
any: {
enter: node => {
pattern.forEach(item => {
Object.keys(node).forEach(key => {
const regex = new RegExp(item, 'i');
if (regex.test(key)) {
delete node[key];
}
});
});
}
}
}
}
```
1. Save the file.
@@ -128,25 +128,25 @@ In this step, two API snapshots are produced from the single source of truth. To
1. Bundle the `external@latest` API.
```bash
redocly bundle external@latest -o dist/bundle-external.yaml
// or
npx @redocly/cli bundle external@latest -o dist/bundle-external.yaml
```
```bash
redocly bundle external@latest -o dist/bundle-external.yaml
// or
npx @redocly/cli bundle external@latest -o dist/bundle-external.yaml
```
Inspect the file at `dist/external.yaml`.
Confirm that all the occurrences of `x-amazon-apigateway` are removed.
Inspect the file at `dist/external.yaml`.
Confirm that all the occurrences of `x-amazon-apigateway` are removed.
1. Bundle the `internal@latest` API.
```bash
redocly bundle internal@latest -o dist/bundle-internal.yaml
// or
npx @redocly/cli bundle internal@latest -o dist/bundle-internal.yaml
```
```bash
redocly bundle internal@latest -o dist/bundle-internal.yaml
// or
npx @redocly/cli bundle internal@latest -o dist/bundle-internal.yaml
```
Inspect the file at `dist/internal.yaml`.
Confirm that all the occurrences of `x-amazon-apigateway` are **not** removed.
Inspect the file at `dist/internal.yaml`.
Confirm that all the occurrences of `x-amazon-apigateway` are **not** removed.
## Advanced usage

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

@@ -12,13 +12,14 @@ This feature is at an early stage, please use with caution and send us lots of f
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:
* AsyncAPI document validation, including full binding validation for [supported protocols](#supported-protocols).
* Supported versions:
- AsyncAPI document validation, including full binding validation for [supported protocols](#supported-protocols).
- Supported versions:
- [AsyncAPI 2.6](https://www.asyncapi.com/docs/reference/specification/v2.6.0)
- earlier versions in the 2.x family may also validate successfully
* Built-in rules for checking common standards requirements (see the [list of AsyncAPI rules](#asyncapi-rules)).
* [Configurable rules](../rules/configurable-rules.md) so that you can build your own rules following common patterns
* [Custom plugins](../custom-plugins/index.md) for advanced users that need additional functionality
- Built-in rules for checking common standards requirements (see the [list of AsyncAPI rules](#asyncapi-rules)).
- [Configurable rules](../rules/configurable-rules.md) so that you can build your own rules following common patterns
- [Custom plugins](../custom-plugins/index.md) for advanced users that need additional functionality
## Lint an existing AsyncAPI file
@@ -44,18 +45,17 @@ redocly lint asyncapi.yaml
The output describes any structural problems with the document, or reports that it is valid.
## AsyncAPI rules
To expand the linting checks for an AsyncAPI description, start by enabling
some of the built-in rules. The currently-supported rules are:
* `info-contact`: the `Info` section must contain a valid `Contact` field.
* `operation-operationId`: every operation must have a valid `operationId`.
* `channels-kebab-case`: channel names should be `kebab-case` (lowercase with hyphens).
* `no-channel-trailing-slash`: channel names must not have trailing slashes in their names.
* `tag-description`: all tags require a description.
* `tags-alphabetical`: tags should be listed in the AsyncAPI file in alphabetical order.
- `info-contact`: the `Info` section must contain a valid `Contact` field.
- `operation-operationId`: every operation must have a valid `operationId`.
- `channels-kebab-case`: channel names should be `kebab-case` (lowercase with hyphens).
- `no-channel-trailing-slash`: channel names must not have trailing slashes in their names.
- `tag-description`: all tags require a description.
- `tags-alphabetical`: tags should be listed in the AsyncAPI file in alphabetical order.
We expect the list to expand over time, so keep checking back - and let us know
if you have any requests by [opening an issue on the GitHub
@@ -110,22 +110,22 @@ them.
AsyncAPI supports an ever-expanding list of protocols, here's the list of what's currently supported:
* `http`
* `ws`
* `kafka`
* `anypointmq`
* `amqp`
* `amqp1`
* `mqtt`
* `mqtt5`
* `nats`
* `jms`
* `sns`
* `solace`
* `sqs`
* `stomp`
* `redis`
* `mercure`
- `http`
- `ws`
- `kafka`
- `anypointmq`
- `amqp`
- `amqp1`
- `mqtt`
- `mqtt5`
- `nats`
- `jms`
- `sns`
- `solace`
- `sqs`
- `stomp`
- `redis`
- `mercure`
If you're using other protocols, you can still use Redocly CLI to lint an
AsyncAPI description, but the details of those protocol bindings aren't

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

@@ -34,9 +34,9 @@ The configuration formats are a little different between the tools.
Redocly uses a configuration file called `redocly.yaml`, the main controls for linting are:
* Specify a [ruleset](../rules.md#rulesets).
* Add configuration for the [rules](../rules.md) accordingly. They can be set to error, warn, or off.
* Expand the collection with any [configurable rules](../rules/configurable-rules.md) that fit your standard.
- Specify a [ruleset](../rules.md#rulesets).
- Add configuration for the [rules](../rules.md) accordingly. They can be set to error, warn, or off.
- Expand the collection with any [configurable rules](../rules/configurable-rules.md) that fit your standard.
### Example Redocly configuration file
@@ -59,14 +59,12 @@ rules:
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
Included here is an attempt to map the simliar-but-not-identical naming of rules between the tools. If you spot anything that needs adding or updating, please [tell us](https://github.com/redocly/redocly-cli/issues/new)?
| Spectral rules | Redocly rules |
|----------------------------------------|-----------------------------------------------|
| -------------------------------------- | --------------------------------------------- |
| `duplicated-entry-in-enum` | |
| `info-contact` | `info-contact` |
| `info-description` | |
@@ -131,6 +129,7 @@ Included here is an attempt to map the simliar-but-not-identical naming of rules
If the built-in rules don't meet your requirements, don't worry! Redocly allows you to build any rule to meet your needs, using [configurable rules](../rules/configurable-rules.md). Declare which elements of the OpenAPI description should comply with the rule, and then define the criteria that it should be checked against.
Build up the rulesets that work for your organization's API standards. These can be:
- using existing Redocly rulesets
- defining your own rulesets from built-in, configurable and/or custom rules
- combining rulesets from any source

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

@@ -72,9 +72,9 @@ redocly bundle openapi.yml
Both commands have additional options; here's a quick reference on how to replace the old with the new:
* Keep `-o` or replace `--outfile` with `--output` to direct the command output to a filename.
* Replace the `-t` or `--type` argument with `--ext` for the file type to output. Redocly CLI also detects the correct format from the output filename, so this option isn't needed for file output, but can be useful if outputting to stdout.
* Replace `-r` or `--dereference` with `-r` or `--dereferenced` to output a file with all `$ref`s resolved.
- Keep `-o` or replace `--outfile` with `--output` to direct the command output to a filename.
- Replace the `-t` or `--type` argument with `--ext` for the file type to output. Redocly CLI also detects the correct format from the output filename, so this option isn't needed for file output, but can be useful if outputting to stdout.
- Replace `-r` or `--dereference` with `-r` or `--dereferenced` to output a file with all `$ref`s resolved.
## Get the best from Redocly CLI

20
docs/installation.md
View File

@@ -2,9 +2,9 @@
Choose the most appropriate installation method for your needs:
* [Install locally, using `npm` or `yarn`](#install-globally) to make the `redocly` command available on your system.
* [Use `npx` to get the tool at runtime](#use-npx-at-runtime) rather than installing it.
* The command is also [available via Docker](#docker) if you'd prefer to use it that way.
- [Install locally, using `npm` or `yarn`](#install-globally) to make the `redocly` command available on your system.
- [Use `npx` to get the tool at runtime](#use-npx-at-runtime) rather than installing it.
- The command is also [available via Docker](#docker) if you'd prefer to use it that way.
## Install globally
@@ -14,14 +14,18 @@ Make sure you have the newest version of `npm`/`yarn` before you begin.
{% tabs %}
{% tab label="npm" %}
```shell
npm i -g @redocly/cli@latest
```
{% /tab %}
{% tab label="yarn" %}
```shell
yarn global add @redocly/cli
```
{% /tab %}
{% /tabs %}
@@ -32,16 +36,21 @@ Running `redocly --version` confirms that the installation was successful, and t
[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.
{% tabs %}
{% tab label="Command" %}
```shell
npx @redocly/cli <command> [options]
```
{% /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).
@@ -49,14 +58,18 @@ Redocly CLI is available as a pre-built Docker image in [Docker Hub](https://hub
Install [Docker](https://docs.docker.com/get-docker/) if you don't have it already, then pull the image with the following command:
{% tabs %}
{% tab label="Docker Hub" %}
```shell
docker pull redocly/cli
```
{% /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:
@@ -69,4 +82,3 @@ docker run --rm -v $PWD:/spec redocly/cli lint petstore.yaml
- Set up [autocomplete for Redocly CLI](./guides/autocomplete.md).
- Check the full list of [Redocly CLI commands](./commands/index.md) available.

5
docs/quickstart.md
View File

@@ -3,8 +3,9 @@
Take your first steps with the Redocly CLI by following the steps in this guide.
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)
- [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)
{% 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

9
docs/rules.md
View File

@@ -7,10 +7,10 @@ seo:
Redocly uses rules to describe all the different aspects of API behavior that we check for during linting. Rules come in different levels of complexity, and can also be grouped for reuse. Here's an overview of what is available:
* **Rulesets** are groups of rules that can be applied to any API. This is a good way to build up a ruleset that you can use locally or with your CI. Multiple rulesets can be used at once, so feel free to make smaller ones and compose the rulesets that fit each API.
* **Built-in rules:** for the most common use cases, the rules are already made for you, all you need to do is choose if they should cause an `error`, simply `warn` of a problem, or be turned `off`. [See the built-in rules documentation](./rules/built-in-rules.md) for more information and examples.
* **Configurable rules** allow powerful describing of API standards without needing to write code. Create a configurable rule, choose which parts of the OpenAPI description it applies to, and what the criteria for success are. The linting tool does the rest. With plenty of examples, the [configurable rules](./rules/configurable-rules.md) helps you to describe your API standards easily and well.
* **Custom code rules** if none of the above exactly fits your needs, then a [custom code plugin](./custom-plugins/index.md) is an extensible way to bring some custom JavaScript to build on Redocly's existing features.
- **Rulesets** are groups of rules that can be applied to any API. This is a good way to build up a ruleset that you can use locally or with your CI. Multiple rulesets can be used at once, so feel free to make smaller ones and compose the rulesets that fit each API.
- **Built-in rules:** for the most common use cases, the rules are already made for you, all you need to do is choose if they should cause an `error`, simply `warn` of a problem, or be turned `off`. [See the built-in rules documentation](./rules/built-in-rules.md) for more information and examples.
- **Configurable rules** allow powerful describing of API standards without needing to write code. Create a configurable rule, choose which parts of the OpenAPI description it applies to, and what the criteria for success are. The linting tool does the rest. With plenty of examples, the [configurable rules](./rules/configurable-rules.md) helps you to describe your API standards easily and well.
- **Custom code rules** if none of the above exactly fits your needs, then a [custom code plugin](./custom-plugins/index.md) is an extensible way to bring some custom JavaScript to build on Redocly's existing features.
## Rulesets
@@ -37,7 +37,6 @@ Severity settings determine how the rule is treated during the validation proces
- `severity: warn` - if the rule is triggered, the output displays a warning message. Your API description may still be valid if no other errors are detected.
- `severity: off` - turns off the rule. The rule is skipped during validation.
## Rule ideas
Redocly CLI supports [configurable rules](./rules/configurable-rules.md) and [custom plugins](./custom-plugins/index.md).

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

@@ -7,12 +7,11 @@ slug: /docs/cli/rules/boolean-parameter-prefixes
Enforces specific and consistent naming for request parameters with `boolean` type.
When this rule is enabled, the `name` fields of all `boolean` parameters in your API must contain one of the configured prefixes.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -45,20 +44,23 @@ If you saw an API with these parameters, you could identify the boolean paramete
- customerReference
The nuance of being able to identify the boolean parameters helps developers produce and consume APIs.
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off`. |
|prefixes|[string]|List of allowed boolean parameter prefixes. Default values are `is` and `has`. |
| Option | Type | Description |
| -------- | -------- | ------------------------------------------------------------------------------ |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. |
| prefixes | [string] | List of allowed boolean parameter prefixes. Default values are `is` and `has`. |
An example configuration:
```yaml
rules:
boolean-parameter-prefixes: error
```
The following example configures prefixes:
```yaml
rules:
boolean-parameter-prefixes:
@@ -93,6 +95,7 @@ schema:
```
## Related rules
- [configurable rules](./configurable-rules.md)
- [no-invalid-parameter-examples](./no-invalid-parameter-examples.md)
- [parameter-description](./parameter-description.md)

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

@@ -6,12 +6,11 @@ slug: /docs/cli/rules/component-name-unique
Verifies component names are unique.
|OAS|Compatibility|
|---|--|
|2.0|❌|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ❌ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -31,13 +30,13 @@ This clearly is not optimal. Having unique component names prevents these proble
## Configuration
| Option |Type| Description |
|---------------|---|------------------------------------------------------------------------------------------|
| severity |string| Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| schemas |string| Possible values: `off`, `warn`, `error`. Default: not set. |
| parameters |string| Possible values: `off`, `warn`, `error`. Default: not set. |
| responses |string| Possible values: `off`, `warn`, `error`. Default: not set. |
| requestBodies |string| Possible values: `off`, `warn`, `error`. Default: not set. |
| Option | Type | Description |
| ------------- | ------ | ---------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| schemas | string | Possible values: `off`, `warn`, `error`. Default: not set. |
| parameters | string | Possible values: `off`, `warn`, `error`. Default: not set. |
| responses | string | Possible values: `off`, `warn`, `error`. Default: not set. |
| requestBodies | string | Possible values: `off`, `warn`, `error`. Default: not set. |
An example configuration:
@@ -52,7 +51,6 @@ rules:
## Examples
Given this configuration:
```yaml
@@ -63,6 +61,7 @@ rules:
### Example of **incorrect** schema files
file1.yaml:
```yaml
components:
schemas:
@@ -74,6 +73,7 @@ components:
```
file2.yaml:
```yaml
components:
schemas:
@@ -87,6 +87,7 @@ components:
### Example of **correct** schema files
file1.yaml:
```yaml
components:
schemas:
@@ -98,6 +99,7 @@ components:
```
file2.yaml:
```yaml
components:
schemas:

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

@@ -6,12 +6,11 @@ slug: /docs/cli/rules/info-contact
Requires the `Contact` info object defined in your API.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -28,9 +27,9 @@ If they need help to purchase, integrate, or troubleshoot, your contact info sho
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off`. |
| Option | Type | Description |
| -------- | ------ | ------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. |
An example configuration:
@@ -42,12 +41,14 @@ rules:
## Examples
Given this configuration:
```yaml
rules:
info-contact: error
```
Example of **incorrect** contact:
```yaml Incorrect example
info:
version: 1.0.0
@@ -59,6 +60,7 @@ info:
```
Example of **correct** contact:
```yaml Correct example
info:
contact:

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/info-license-url
---
# info-license-url
Requires the license URL in your API descriptions.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -30,9 +30,9 @@ By being upfront with the API license, you can reduce friction and encourage API
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ----------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
An example configuration:
@@ -44,6 +44,7 @@ rules:
## Examples
Given the following configuration:
```yaml
rules:
info-license-url: error
@@ -75,4 +76,3 @@ info:
- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/common/info-license-url.ts)
- [License object docs](https://redocly.com/docs/openapi-visual-reference/license/)

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/info-license
---
# info-license
Requires the license info in your API descriptions.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -30,9 +30,9 @@ By being upfront with the API license, you can reduce friction and encourage API
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ----------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
An example configuration:
@@ -44,6 +44,7 @@ rules:
## Examples
Given the following configuration:
```yaml
rules:
info-license: error

55
docs/rules/minimal.md
View File

@@ -1,39 +1,40 @@
---
slug: /docs/cli/rules/minimal
---
# Minimal ruleset
The rules contained in the minimal ruleset:
Errors:
* [no-server-trailing-slash](./no-server-trailing-slash.md)
* [no-server-variables-empty-enum](./no-server-variables-empty-enum.md)
* [no-unresolved-refs](./no-unresolved-refs.md)
* [spec](./spec.md)
- [no-server-trailing-slash](./no-server-trailing-slash.md)
- [no-server-variables-empty-enum](./no-server-variables-empty-enum.md)
- [no-unresolved-refs](./no-unresolved-refs.md)
- [spec](./spec.md)
Warnings:
* [configurable rules](./configurable-rules.md)
* [no-ambiguous-paths](./no-ambiguous-paths.md)
* [no-empty-servers](./no-empty-servers.md)
* [no-enum-type-mismatch](./no-enum-type-mismatch.md)
* [no-example-value-and-externalValue](./no-example-value-and-externalValue.md)
* [no-identical-paths](./no-identical-paths.md)
* [no-invalid-media-type-examples](./no-invalid-media-type-examples.md)
* [no-path-trailing-slash](./no-path-trailing-slash.md)
* [no-server-example.com](./no-server-example-com.md)
* [no-undefined-server-variable](./no-undefined-server-variable.md)
* [no-unused-components](./no-unused-components.md)
* [operation-2xx-response](./operation-2xx-response.md)
* [operation-operationId-unique](./operation-operationId-unique.md)
* [operation-operationId-url-safe](./operation-operationId-url-safe.md)
* [operation-operationId](./operation-operationId.md)
* [operation-parameters-unique](./operation-parameters-unique.md)
* [operation-summary](./operation-summary.md)
* [path-declaration-must-exist](./path-declaration-must-exist.md)
* [path-not-include-query](./path-not-include-query.md)
* [path-parameters-defined](./path-parameters-defined.md)
* [security-defined](./security-defined.md)
* [spec-components-invalid-map-name](./spec-components-invalid-map-name.md)
* [tag-description](./tag-description.md)
- [configurable rules](./configurable-rules.md)
- [no-ambiguous-paths](./no-ambiguous-paths.md)
- [no-empty-servers](./no-empty-servers.md)
- [no-enum-type-mismatch](./no-enum-type-mismatch.md)
- [no-example-value-and-externalValue](./no-example-value-and-externalValue.md)
- [no-identical-paths](./no-identical-paths.md)
- [no-invalid-media-type-examples](./no-invalid-media-type-examples.md)
- [no-path-trailing-slash](./no-path-trailing-slash.md)
- [no-server-example.com](./no-server-example-com.md)
- [no-undefined-server-variable](./no-undefined-server-variable.md)
- [no-unused-components](./no-unused-components.md)
- [operation-2xx-response](./operation-2xx-response.md)
- [operation-operationId-unique](./operation-operationId-unique.md)
- [operation-operationId-url-safe](./operation-operationId-url-safe.md)
- [operation-operationId](./operation-operationId.md)
- [operation-parameters-unique](./operation-parameters-unique.md)
- [operation-summary](./operation-summary.md)
- [path-declaration-must-exist](./path-declaration-must-exist.md)
- [path-not-include-query](./path-not-include-query.md)
- [path-parameters-defined](./path-parameters-defined.md)
- [security-defined](./security-defined.md)
- [spec-components-invalid-map-name](./spec-components-invalid-map-name.md)
- [tag-description](./tag-description.md)

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

@@ -1,6 +1,7 @@
---
slug: /docs/cli/rules/no-ambiguous-paths/
---
# no-ambiguous-paths
Ensures there are no ambiguous paths in your API descriptions.
@@ -18,11 +19,11 @@ According to the OpenAPI specification:
> /{entity}/me
> /books/{id}
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -46,9 +47,9 @@ Such paths are considered ambiguous and should be avoided, because API users and
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ----------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
An example configuration:

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/np-empty-servers
---
# no-empty-servers
Requires the `servers` list is defined in your API.
|OAS|Compatibility|
|---|---|
|2.0|❌|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ❌ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -19,11 +19,12 @@ root ==> ServersList
style ServersList fill:#codaf9,stroke:#0044d4,stroke-width:5px
```
## API design principles
An empty `servers` list defaults to `localhost`, which is not practical for your API consumers.
An API cannot be used without a server.
Define servers so that the *Try it* and code sample generator features in OpenAPI tools (including Redocly) can produce functional API requests.
Define servers so that the _Try it_ and code sample generator features in OpenAPI tools (including Redocly) can produce functional API requests.
If you don't have a server because the consumer is responsible for setting up their own server, you can still describe the server with server variables.
The following code sample shows declaration of a server variable.
@@ -39,9 +40,9 @@ servers:
## 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:
@@ -74,6 +75,7 @@ servers:
```
## Related rules
- [no-server-example.com](./no-server-example-com.md)
- [no-server-trailing-slash](./no-server-trailing-slash.md)

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

@@ -6,12 +6,11 @@ slug: /docs/cli/rules/no-enum-type-mismatch
Requires that the contents of every `enum` value in your API description conform to the corresponding schema's specified `type`.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -39,9 +38,9 @@ Lack of compliance is most likely the result of a typo.
## 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:
@@ -60,6 +59,7 @@ rules:
```
Example of **incorrect** enum values given the enum type:
```yaml Bad example
properties:
huntingSkill:
@@ -72,6 +72,7 @@ properties:
```
Example of **correct** enum values given the enum type:
```yaml Good example
properties:
huntingSkill:

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

@@ -6,11 +6,11 @@ slug: /docs/cli/rules/no-example-value-and-externalValue
Ensures that `examples` object properties `externalValue` and `value` are mutually exclusive.
|OAS|Compatibility|
|---|---|
|2.0|❌|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ❌ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -39,9 +39,9 @@ The intended use of the `value` field is to provide in-line example values, whil
## 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:
@@ -53,12 +53,14 @@ rules:
## Examples
Given this configuration:
```yaml
rules:
no-example-value-and-externalValue: error
```
Example of an **incorrect** example object:
```yaml Bad example
requestBody:
content:

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

@@ -6,12 +6,11 @@ slug: /docs/cli/rules/no-http-verbs-in-paths
Disallows HTTP verbs used in paths.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -21,6 +20,7 @@ style Paths fill:#codaf9,stroke:#0044d4,stroke-width:5px
```
List of HTTP verbs:
- `get`
- `head`
- `post`
@@ -30,7 +30,6 @@ List of HTTP verbs:
- `options`
- `trace`
## API design principles
API designers generally fall into either a REST or RPC type.
@@ -45,10 +44,10 @@ With the `splitIntoWords` option enabled, "posters" is identified as a resource
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
|splitIntoWords|boolean|Matches http verbs when the string is split into words based on casing. This can reduce false positives. Default **false**.|
| Option | Type | Description |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| splitIntoWords | boolean | Matches http verbs when the string is split into words based on casing. This can reduce false positives. Default **false**. |
An example configuration:
@@ -83,7 +82,6 @@ paths:
$ref: ./paths/customer.yaml
```
Example of a **correct** path:
```yaml Good example
@@ -92,7 +90,6 @@ paths:
$ref: ./paths/customer.yaml
```
Given the following configuration:
```yaml
@@ -129,4 +126,3 @@ This last example wouldn't trigger an error because the casing doesn't split "ge
- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/common/no-http-verbs-in-paths.ts)
- [Paths docs](https://redocly.com/docs/openapi-visual-reference/paths/)

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

@@ -1,15 +1,16 @@
---
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.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
According to the OpenAPI specification:
@@ -33,9 +34,9 @@ Minimize it in APIs to make them as easy as possible to use.
## 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:
@@ -53,7 +54,6 @@ rules:
no-identical-paths: error
```
Example of **incorrect** paths:
```yaml
@@ -78,6 +78,7 @@ paths:
- [no-ambiguous-paths](./no-ambiguous-paths.md)
- [spec](./spec.md)
## Resources
- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/common/no-identical-paths.ts)

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

@@ -6,11 +6,11 @@ slug: /docs/cli/rules/no-invalid-media-type-examples
Disallow invalid media type examples by ensuring they comply with the corresponding schema definitions.
|OAS|Compatibility|
|---|---|
|2.0|❌|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ❌ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -40,12 +40,13 @@ Most likely there is either a mistake with the example or the schema (or both).
Trust us.
It's much nicer to get this alert from Redocly before you ship than from your biggest customer three months later.
## Configuration
|Option|Type| Description |
|---|---|-------------------------------------------------------------------------------|
|severity|string| Possible values: `off`, `warn`, `error`. Default `warn`. |
|allowAdditionalProperties|boolean| Determines if additional properties are allowed in examples. Default `false`. |
| Option | Type | Description |
| ------------------------- | ------- | ----------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `warn`. |
| allowAdditionalProperties | boolean | Determines if additional properties are allowed in examples. Default `false`. |
An example configuration:
@@ -91,8 +92,8 @@ post:
model: Y
year: '2022'
```
> This example produces an error because the year is a string instead of an integer.
> This example produces an error because the year is a string instead of an integer.
Example of a **correct** media type example:

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

@@ -6,11 +6,11 @@ slug: /docs/cli/rules/no-invalid-parameter-examples
Disallow invalid parameter examples.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -40,10 +40,10 @@ Solve it before you ship it.
## Configuration
|Option|Type| Description |
|---|---|-------------------------------------------------------------------------------|
|severity|string| Possible values: `off`, `warn`, `error`. Default `warn`. |
|allowAdditionalProperties|boolean| Determines if additional properties are allowed in examples. Default `false`. |
| Option | Type | Description |
| ------------------------- | ------- | ----------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `warn`. |
| allowAdditionalProperties | boolean | Determines if additional properties are allowed in examples. Default `false`. |
```yaml
rules:

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

@@ -6,11 +6,11 @@ slug: /docs/cli/rules/no-invalid-schema-examples
Disallow invalid schema examples.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -34,6 +34,7 @@ style Example fill:#codaf9,stroke:#0044d4,stroke-width:5px
style Schema fill:#codaf9,stroke:#0044d4,stroke-width:5px
style NamedSchema fill:#codaf9,stroke:#0044d4,stroke-width:5px
```
## API design principles
If your schema and example conflict, there is a problem in the definition of the schema or the example.
@@ -41,10 +42,10 @@ Solve it before you ship it.
## Configuration
|Option|Type| Description |
|---|---|-------------------------------------------------------------------------------|
|severity|string| Possible values: `off`, `warn`, `error`. Default `warn`. |
|allowAdditionalProperties|boolean| Determines if additional properties are allowed in examples. Default `false`. |
| Option | Type | Description |
| ------------------------- | ------- | ----------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `warn`. |
| allowAdditionalProperties | boolean | Determines if additional properties are allowed in examples. Default `false`. |
An example configuration:

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

@@ -1,15 +1,16 @@
---
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 (`/`).
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -22,9 +23,9 @@ When it comes to developer experience, consistency rules.
## 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:
@@ -36,12 +37,12 @@ rules:
## Examples
Given this configuration:
```yaml
rules:
no-path-trailing-slash: error
```
Example of **incorrect** path:
```yaml
@@ -63,8 +64,8 @@ paths:
- [no-server-trailing-slash](./no-server-trailing-slash.md)
- [path-not-include-query](./path-not-include-query.md)
- [path-declaration-must-exist](./path-declaration-must-exist.md)
## Resources
- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/common/no-path-trailing-slash.ts)
- [Paths object docs](https://redocly.com/docs/openapi-visual-reference/paths/)

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

@@ -1,17 +1,17 @@
---
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.
The rule checks for all URL schemes (`http`, `https`...).
|OAS|Compatibility|
|---|---|
|2.0|❌|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ❌ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -31,9 +31,9 @@ If you can't reveal a production server, consider a [Redocly mock server](/docs/
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ----------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
An example configuration:
@@ -72,7 +72,6 @@ servers:
- [no-empty-servers](./no-empty-servers.md)
- [no-server-trailing-slash](./no-server-trailing-slash.md)
## Resources
- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/oas3/no-server-example.com.ts)

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/no-server-trailing-slash
---
# no-server-trailing-slash
Disallow servers with a trailing slash.
|OAS|Compatibility|
|---|---|
|2.0|❌|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ❌ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -33,9 +33,9 @@ Hands-down a good rule for every API designer.
## 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:

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/no-undefined-server-variable
---
# no-undefined-server-variable
Disallow undefined server variables.
|OAS|Compatibility|
|---|---|
|2.0|❌|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ❌ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -28,9 +28,9 @@ It is important to fix these errors to help clients consume APIs.
## 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:

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/no-unresolved
---
# no-unresolved-refs
Ensures that all `$ref` instances in your API descriptions are resolved.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -20,10 +20,9 @@ This rule prevents that from happening.
## 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:
@@ -93,4 +92,3 @@ components:
- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/no-unresolved-refs.ts)
- Read our guide on [how to use JSON references ($refs)](/docs/resources/ref-guide.md)

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

@@ -1,17 +1,17 @@
---
slug: /docs/cli/rules/no-unused-components
---
# no-unused-components
Ensures that every component specified in your API description is used at least once.
In this context, "used" means that a component defined in the `components` object is referenced elsewhere in the API document with `$ref`.
|OAS|Compatibility|
|---|---|
|2.0|❌|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ❌ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -30,10 +30,9 @@ If that describes your use-case, turn this rule off.
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ----------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
An example configuration:
@@ -65,6 +64,7 @@ components:
dealers:
# ...
```
> The dealers `PathItem` is an unused component.
Example of **correct** components:
@@ -83,6 +83,7 @@ components:
## Relates rules
- [no-undefined-refs](./no-unresolved-refs.md)
## Resources
- The Redocly CLI `bundle` command supports an option called `--remove-unused-components`. Use it to automatically clean up any unused components from your OpenAPI document while bundling it.

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

@@ -6,12 +6,11 @@ slug: /docs/cli/rules/operation-2xx-response
Ensures that every operation in your API document has at least one successful (200-299) HTTP response defined.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -24,10 +23,10 @@ You can greatly improve the developer and user experience of your APIs by making
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
|validateWebhooks|boolean|Determines if responses inside webhooks are validated. Default `false`. |
| Option | Type | Description |
| ---------------- | ------- | ----------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
| validateWebhooks | boolean | Determines if responses inside webhooks are validated. Default `false`. |
An example configuration:
@@ -55,6 +54,7 @@ rules:
```
Example of **incorrect** operation response:
```yaml
post:
responses:

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

@@ -1,6 +1,7 @@
---
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`.

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

@@ -6,11 +6,11 @@ slug: /docs/cli/rules/operation-4xx-response
Ensures that every operation in your API document has at least one error (400-499) HTTP response defined.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -22,10 +22,10 @@ While this thinking has mostly changed (for the better in our opinion), it does
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
|validateWebhooks|boolean|Determines if responses inside webhooks are validated. Default `false`. |
| Option | Type | Description |
| ---------------- | ------- | ----------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
| validateWebhooks | boolean | Determines if responses inside webhooks are validated. Default `false`. |
An example configuration:
@@ -53,6 +53,7 @@ rules:
```
Example of **incorrect** operation response:
```yaml
post:
responses:
@@ -70,6 +71,7 @@ post:
'400':
$ref: ../components/responses/Problem.yaml
```
## Related rules
- [operation-2xx-response](./operation-2xx-response.md)

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/operation-description
---
# operation-description
Requires the `description` field for every operation in your API.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -20,9 +20,9 @@ Add the description field and delight both your (future) teammates and your API
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ---------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
An example configuration:
@@ -41,6 +41,7 @@ rules:
```
Example of an **incorrect** operation:
```yaml
get:
responses:

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

@@ -1,15 +1,16 @@
---
slug: /docs/cli/rules/operation-operationId-unique
---
# operation-operationId-unique
Requires unique `operationId` values for each operation.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principle
@@ -21,9 +22,9 @@ This rule is unopinionated.
## 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:
@@ -42,6 +43,7 @@ rules:
```
Example of **incorrect** operations:
```yaml
paths:
/cars:
@@ -54,6 +56,7 @@ paths:
```
Example of **correct** operations:
```yaml
paths:
/cars:

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

@@ -1,15 +1,16 @@
---
slug: /docs/cli/rules/operation-operationId-url-safe
---
# operation-operationId-url-safe
Requires the `operationId` value to be URL safe.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -18,11 +19,12 @@ Some tooling may use it in a URL path.
This rule makes it possible to use the `operationId` in URLs without any transformation of the `operationId`.
This rule is unopinionated.
## 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:
@@ -41,6 +43,7 @@ rules:
```
Example of an **incorrect** operation:
```yaml
paths:
/cars:
@@ -50,6 +53,7 @@ paths:
```
Example of a **correct** operation:
```yaml
paths:
/cars:

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

@@ -1,15 +1,16 @@
---
slug: /docs/cli/rules/operation-operationId
---
# operation-operationId
Requires each operation to have an `operationId` defined.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -18,11 +19,12 @@ The `operationId` is used by tooling to identify operations (which are otherwise
This rule is unopinionated.
If it annoys the lazy or minimalists, offer them an alternative: two weeks at Redocly Bootcamp.
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ----------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `warn` (in `recommended` configuration). |
An example configuration:
@@ -41,6 +43,7 @@ rules:
```
Example of an **incorrect** operation:
```yaml
paths:
/cars:
@@ -51,6 +54,7 @@ paths:
```
Example of a **correct** operation:
```yaml
paths:
/cars:

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/operation-parameters-unique
---
# operation-parameters-unique
Verifies parameters are unique for any given operation.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -21,9 +21,9 @@ Solve it before you ship it.
## 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:
@@ -34,7 +34,6 @@ rules:
## Examples
Given this configuration:
```yaml

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/operation-singular-tag
---
# operation-singular-tag
Disallows multiple tags for an operation.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -23,10 +23,9 @@ Simple wins.
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ---------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
An example configuration:

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/operation-summary
---
# operation-summary
Enforce that every operation has a summary.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -19,10 +19,9 @@ Redocly uses the summary as the header for the operation, as well as the sidebar
## 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:

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/operation-tag-defined
---
# operation-tag-defined
Disallows use of tags in operations that aren't globally defined.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -23,10 +23,9 @@ This rule helps prevent typos and tag explosion.
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ---------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
An example configuration:
@@ -37,7 +36,6 @@ rules:
## Examples
Given this configuration:
```yaml

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/parameter-description
---
# parameter-description
Ensure that every parameter has a description.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -20,10 +20,9 @@ Document it!
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ---------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
An example configuration:
@@ -34,7 +33,6 @@ rules:
## Examples
Given this configuration:
```yaml

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/path-declaration-must-exist
---
# path-declaration-must-exist
Requires definition of all path template variables.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -20,10 +20,9 @@ This rule is not opinionated.
## 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:
@@ -34,7 +33,6 @@ rules:
## Examples
Given this configuration:
```yaml

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

@@ -1,17 +1,16 @@
---
slug: /docs/cli/rules/path-excludes-patterns
---
# path-excludes-patterns
Disallow patterns from paths.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -25,12 +24,10 @@ Other ideas are around casing (other than kebab-case, which is a common approach
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration).
|patterns|[string]|List of patterns to match. For example, `^\/[a-z]`.
| Option | Type | Description |
| -------- | -------- | ---------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| patterns | [string] | List of patterns to match. For example, `^\/[a-z]`. |
An example configuration:

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

@@ -1,16 +1,17 @@
---
slug: /docs/cli/rules/path-not-include-query
---
# path-not-include-query
Path should not include query parameters.
The query parameters should be defined on the `PathItem` or `Operation`.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -20,10 +21,9 @@ Its root cause is inexperience with OpenAPI (no holy war here).
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ---------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
An example configuration:
@@ -34,7 +34,6 @@ rules:
## Examples
Given this configuration:
```yaml

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/path-parameters-defined
---
# path-parameters-defined
Requires all path template variables are defined as path parameters.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -20,10 +20,9 @@ This rule verifies the path parameters are defined.
## 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:
@@ -34,7 +33,6 @@ rules:
## Examples
Given this configuration:
```yaml

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/path-segment-plural
---
# path-segment-plural
Enforces plural path segments.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -27,12 +27,11 @@ Nothing wrong with that.
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
|ignoreLastPathSegment|boolean|Ignores the last path segment if true. Default value: `false`.|
|exceptions|[string]|List of strings to exclude when checking path segments, for example, `v1`.|
| Option | Type | Description |
| --------------------- | -------- | ---------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| ignoreLastPathSegment | boolean | Ignores the last path segment if true. Default value: `false`. |
| exceptions | [string] | List of strings to exclude when checking path segments, for example, `v1`. |
An example configuration:

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/paths-kebab-case
---
# paths-kebab-case
Require kebab-case in paths instead of camelCase or snake_case.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -29,10 +29,9 @@ We don't want to say we told ya so!
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ---------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
An example configuration:
@@ -43,7 +42,6 @@ rules:
## Examples
Given this configuration:
```yaml

61
docs/rules/recommended.md
View File

@@ -1,45 +1,46 @@
---
slug: /docs/cli/rules/recommended
---
# Recommended ruleset
These are the rules in the `recommended` set, grouped by their severity.
Errors:
* [no-empty-servers](./no-empty-servers.md)
* [no-enum-type-mismatch](./no-enum-type-mismatch.md)
* [no-example-value-and-externalValue](./no-example-value-and-externalValue.md)
* [no-identical-paths](./no-identical-paths.md)
* [no-path-trailing-slash](./no-path-trailing-slash.md)
* [no-server-trailing-slash](./no-server-trailing-slash.md)
* [no-server-variables-empty-enum](./no-server-variables-empty-enum.md)
* [no-undefined-server-variable](./no-undefined-server-variable.md)
* [no-unresolved-refs](./no-unresolved-refs.md)
* [operation-operationId-unique](./operation-operationId-unique.md)
* [operation-operationId-url-safe](./operation-operationId-url-safe.md)
* [operation-parameters-unique](./operation-parameters-unique.md)
* [operation-summary](./operation-summary.md)
* [path-declaration-must-exist](./path-declaration-must-exist.md)
* [path-not-include-query](./path-not-include-query.md)
* [path-parameters-defined](./path-parameters-defined.md)
* [security-defined](./security-defined.md)
* [spec-components-invalid-map-name](./spec-components-invalid-map-name.md)
* [spec](./spec.md)
- [no-empty-servers](./no-empty-servers.md)
- [no-enum-type-mismatch](./no-enum-type-mismatch.md)
- [no-example-value-and-externalValue](./no-example-value-and-externalValue.md)
- [no-identical-paths](./no-identical-paths.md)
- [no-path-trailing-slash](./no-path-trailing-slash.md)
- [no-server-trailing-slash](./no-server-trailing-slash.md)
- [no-server-variables-empty-enum](./no-server-variables-empty-enum.md)
- [no-undefined-server-variable](./no-undefined-server-variable.md)
- [no-unresolved-refs](./no-unresolved-refs.md)
- [operation-operationId-unique](./operation-operationId-unique.md)
- [operation-operationId-url-safe](./operation-operationId-url-safe.md)
- [operation-parameters-unique](./operation-parameters-unique.md)
- [operation-summary](./operation-summary.md)
- [path-declaration-must-exist](./path-declaration-must-exist.md)
- [path-not-include-query](./path-not-include-query.md)
- [path-parameters-defined](./path-parameters-defined.md)
- [security-defined](./security-defined.md)
- [spec-components-invalid-map-name](./spec-components-invalid-map-name.md)
- [spec](./spec.md)
Warnings:
* [configurable rules](./configurable-rules.md)
* [info-license-url](./info-license-url.md)
* [info-license](./info-license.md)
* [no-ambiguous-paths](./no-ambiguous-paths.md)
* [no-invalid-media-type-examples](./no-invalid-media-type-examples.md)
* [no-server-example.com](./no-server-example-com.md)
* [no-unused-components](./no-unused-components.md)
* [operation-2xx-response](./operation-2xx-response.md)
* [operation-4xx-response](./operation-4xx-response.md)
* [operation-operationId](./operation-operationId.md)
* [tag-description](./tag-description.md)
- [configurable rules](./configurable-rules.md)
- [info-license-url](./info-license-url.md)
- [info-license](./info-license.md)
- [no-ambiguous-paths](./no-ambiguous-paths.md)
- [no-invalid-media-type-examples](./no-invalid-media-type-examples.md)
- [no-server-example.com](./no-server-example-com.md)
- [no-unused-components](./no-unused-components.md)
- [operation-2xx-response](./operation-2xx-response.md)
- [operation-4xx-response](./operation-4xx-response.md)
- [operation-operationId](./operation-operationId.md)
- [tag-description](./tag-description.md)
## Recommended strict ruleset

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

@@ -1,13 +1,14 @@
---
slug: /docs/cli/rules/request-mine-type
---
# request-mime-type
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -25,11 +26,10 @@ It doesn't matter to me... keep it consistent across your entire API if possible
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|**REQUIRED.** Possible values: `off`, `warn`, `error`.|
|allowedValues|[string]|**REQUIRED.** List of allowed request mime types.|
| Option | Type | Description |
| ------------- | -------- | ------------------------------------------------------ |
| severity | string | **REQUIRED.** Possible values: `off`, `warn`, `error`. |
| allowedValues | [string] | **REQUIRED.** List of allowed request mime types. |
An example configuration:

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

@@ -1,15 +1,16 @@
---
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`.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -26,9 +27,9 @@ rules:
severity: error
```
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ---------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
An example configuration:
@@ -39,7 +40,6 @@ rules:
## Examples
Given this configuration:
```yaml
@@ -64,7 +64,6 @@ schemas:
Example of a **correct** schema:
```yaml Good example
schemas:
User:

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

@@ -1,15 +1,16 @@
---
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.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -17,11 +18,10 @@ In some cases, it is important to design an API so that it consistently returns
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|**REQUIRED.** Possible values: `off`, `warn`, `error`.|
|names|Map (HTTP response code or range, [string])|**REQUIRED.** For a given HTTP response code or range, the corresponding list of expected HTTP response headers.|
| Option | Type | Description |
| -------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| severity | string | **REQUIRED.** Possible values: `off`, `warn`, `error`. |
| names | Map (HTTP response code or range, [string]) | **REQUIRED.** For a given HTTP response code or range, the corresponding list of expected HTTP response headers. |
An example configuration:

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

@@ -1,16 +1,16 @@
---
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.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -18,11 +18,10 @@ In some cases, it is important to design an API so that it consistently returns
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|**REQUIRED.** Possible values: `off`, `warn`, `error`.|
|names|Map (HTTP response code or range, [string])|**REQUIRED.** For a given HTTP response code or range, the corresponding list of expected response properties.|
| Option | Type | Description |
| -------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| severity | string | **REQUIRED.** Possible values: `off`, `warn`, `error`. |
| names | Map (HTTP response code or range, [string]) | **REQUIRED.** For a given HTTP response code or range, the corresponding list of expected response properties. |
An example configuration:
@@ -40,7 +39,6 @@ rules:
## Examples
Given this configuration:
```yaml

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

@@ -1,14 +1,14 @@
---
slug: /docs/cli/rules/response-mime-type
---
# response-mime-type
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -27,10 +27,10 @@ Keep it consistent across your entire API if possible.
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|**REQUIRED.** Possible values: `off`, `warn`, `error`.|
|allowedValues|[string]|**REQUIRED.** List of allowed response mime types.|
| Option | Type | Description |
| ------------- | -------- | ------------------------------------------------------ |
| severity | string | **REQUIRED.** Possible values: `off`, `warn`, `error`. |
| allowedValues | [string] | **REQUIRED.** List of allowed response mime types. |
An example configuration:
@@ -42,6 +42,7 @@ rules:
- application/json
- image/png
```
## Examples
Given this configuration:

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

@@ -1,16 +1,17 @@
---
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.
Scalar properties are any of the following types: `string`, `number`, `null`, `boolean`, `integer`.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -29,9 +30,9 @@ rules:
severity: error
```
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ---------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
An example configuration:
@@ -42,7 +43,6 @@ rules:
## Examples
Given this configuration:
```yaml
@@ -65,7 +65,6 @@ schemas:
Example of a **correct** schema:
```yaml Good example
schemas:
User:

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

@@ -1,15 +1,16 @@
---
slug: /docs/cli/rules/security-defined
---
# security-defined
Verifies every operation or global security is defined.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -30,12 +31,12 @@ Even if the API is truly public without any credential required, define the empt
# This API has no security
security: []
```
## 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:

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

@@ -1,15 +1,16 @@
---
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\.\-_]+$`.
|OAS|Compatibility|
|---|---|
|2.0|❌|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ❌ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```mermaid
flowchart TD
@@ -46,9 +47,9 @@ All the fixed fields declared below are objects that MUST use keys that match 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:
@@ -67,6 +68,7 @@ rules:
```
Example of **incorrect** operation response:
```yaml
components:
examples:

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

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

18
docs/rules/spec.md
View File

@@ -1,16 +1,16 @@
---
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).
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
The default setting for this rule (in the `recommended` and `minimal` configuration) is `error`.
@@ -22,9 +22,9 @@ It's important to conform to the specification so that tools work with your API
## 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:

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

@@ -1,16 +1,16 @@
---
slug: /docs/cli/rules/tag-description
---
# tag-description
Requires that the tags all have a non-empty `description`.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
```yaml Object structure
tags:
@@ -48,10 +48,9 @@ rules:
info-contact: error
```
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| Option | Type | Description |
| -------- | ------ | ---------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
An example configuration:
@@ -62,7 +61,6 @@ rules:
## Examples
Given this configuration:
```yaml

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

@@ -1,18 +1,18 @@
---
slug: /docs/cli/rules/tags-alphabetical
---
# tags-alphabetical
Ensures that all tag `name` fields in the `tags` object are listed in alphabetical order.
Note that this rule does not automatically sort your tags if they are not in alphabetical order.
The rule only produces a warning or an error, and expects you to modify your API descriptions.
|OAS|Compatibility|
|---|---|
|2.0|✅|
|3.0|✅|
|3.1|✅|
| OAS | Compatibility |
| --- | ------------- |
| 2.0 | ✅ |
| 3.0 | ✅ |
| 3.1 | ✅ |
## API design principles
@@ -32,11 +32,10 @@ This rule is intended to prevent bikeshedding and diffuse tension between teamma
## Configuration
|Option|Type|Description|
|---|---|---|
|severity|string|Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
|ignoreCase|boolean|Possible values: `true`, `false`. Default `false` (in `recommended` configuration). |
| Option | Type | Description |
| ---------- | ------- | ---------------------------------------------------------------------------------------- |
| severity | string | Possible values: `off`, `warn`, `error`. Default `off` (in `recommended` configuration). |
| ignoreCase | boolean | Possible values: `true`, `false`. Default `false` (in `recommended` configuration). |
An example configuration:

11
docs/usage-data.md
View File

@@ -10,11 +10,12 @@ Redocly CLI sends a small set of anonymized data to help us understand how the t
## What data is collected
When a command is run, the following data is collected:
* the command being run
* command exit code
* values from `REDOCLY_ENVIRONMENT`
* CLI version
* Node.js and NPM versions
- the command being run
- command exit code
- values from `REDOCLY_ENVIRONMENT`
- CLI version
- Node.js and NPM versions
Values such as file names, organization IDs, and URLs are removed, replaced by just "URL" or "file", etc.