From d16e9a13b19ac42da4ff0e730e0edaca02b3fff1 Mon Sep 17 00:00:00 2001 From: Lorna Mitchell Date: Fri, 17 Nov 2023 09:31:42 +0000 Subject: [PATCH] chore: Run prettier on all docs files --- .prettierrc.json | 3 +- docs/api-docs.md | 17 ++- docs/api-standards.md | 6 +- docs/changelog.md | 10 +- docs/commands/build-docs.md | 2 +- docs/commands/lint.md | 62 +++++++++-- docs/custom-plugins/custom-config.md | 4 +- docs/custom-plugins/custom-decorators.md | 5 +- docs/custom-plugins/custom-rules.md | 8 +- docs/custom-plugins/index.md | 2 - docs/custom-plugins/visitor.md | 5 - docs/decorators/filter-in.md | 11 +- docs/decorators/filter-out.md | 10 +- docs/decorators/info-description-override.md | 8 +- docs/decorators/info-override.md | 7 +- .../media-type-examples-override.md | 7 +- .../operation-description-override.md | 8 +- docs/decorators/remove-x-internal.md | 6 +- docs/decorators/tag-description-override.md | 8 +- docs/file-management.md | 12 +-- docs/guides/autocomplete.md | 2 +- docs/guides/change-token-url.md | 22 ++-- docs/guides/configure-rules.md | 17 +-- docs/guides/hide-specification-extensions.md | 102 +++++++++--------- docs/guides/lint-asyncapi.md | 56 +++++----- docs/guides/migrate-from-spectral.md | 11 +- docs/guides/migrate-from-swagger-cli.md | 6 +- docs/installation.md | 20 +++- docs/quickstart.md | 5 +- docs/rules.md | 9 +- docs/rules/boolean-parameter-prefixes.md | 23 ++-- docs/rules/component-name-unique.md | 30 +++--- docs/rules/info-contact.md | 20 ++-- docs/rules/info-license-url.md | 20 ++-- docs/rules/info-license.md | 19 ++-- docs/rules/minimal.md | 55 +++++----- docs/rules/no-ambiguous-paths.md | 17 +-- docs/rules/no-empty-servers.md | 22 ++-- docs/rules/no-enum-type-mismatch.md | 19 ++-- .../no-example-value-and-externalValue.md | 18 ++-- docs/rules/no-http-verbs-in-paths.md | 24 ++--- docs/rules/no-identical-paths.md | 19 ++-- docs/rules/no-invalid-media-type-examples.md | 21 ++-- docs/rules/no-invalid-parameter-examples.md | 18 ++-- docs/rules/no-invalid-schema-examples.md | 19 ++-- docs/rules/no-path-trailing-slash.md | 21 ++-- docs/rules/no-server-example-com.md | 19 ++-- docs/rules/no-server-trailing-slash.md | 18 ++-- docs/rules/no-undefined-server-variable.md | 18 ++-- docs/rules/no-unresolved-refs.md | 20 ++-- docs/rules/no-unused-components.md | 21 ++-- docs/rules/operation-2xx-response.md | 20 ++-- .../operation-4xx-problem-details-rfc7807.md | 1 + docs/rules/operation-4xx-response.md | 20 ++-- docs/rules/operation-description.md | 19 ++-- docs/rules/operation-operationId-unique.md | 19 ++-- docs/rules/operation-operationId-url-safe.md | 20 ++-- docs/rules/operation-operationId.md | 20 ++-- docs/rules/operation-parameters-unique.md | 19 ++-- docs/rules/operation-singular-tag.md | 19 ++-- docs/rules/operation-summary.md | 19 ++-- docs/rules/operation-tag-defined.md | 20 ++-- docs/rules/parameter-description.md | 20 ++-- docs/rules/path-declaration-must-exist.md | 20 ++-- docs/rules/path-excludes-patterns.md | 23 ++-- docs/rules/path-not-include-query.md | 19 ++-- docs/rules/path-parameters-defined.md | 20 ++-- docs/rules/path-segment-plural.md | 23 ++-- docs/rules/paths-kebab-case.md | 20 ++-- docs/rules/recommended.md | 61 +++++------ docs/rules/request-mime-type.md | 20 ++-- ...ired-string-property-missing-min-length.md | 19 ++-- docs/rules/response-contains-header.md | 20 ++-- docs/rules/response-contains-property.md | 22 ++-- docs/rules/response-mime-type.md | 21 ++-- docs/rules/scalar-property-missing-example.md | 19 ++-- docs/rules/security-defined.md | 19 ++-- .../rules/spec-components-invalid-map-name.md | 18 ++-- docs/rules/spec-strict-refs.md | 1 + docs/rules/spec.md | 18 ++-- docs/rules/tag-description.md | 20 ++-- docs/rules/tags-alphabetical.md | 21 ++-- docs/usage-data.md | 11 +- 83 files changed, 796 insertions(+), 747 deletions(-) diff --git a/.prettierrc.json b/.prettierrc.json index 5ac85e271d..788262b726 100644 --- a/.prettierrc.json +++ b/.prettierrc.json @@ -1,4 +1,5 @@ { "printWidth": 100, - "singleQuote": true + "singleQuote": true, + "embeddedLanguageFormatting": "off" } diff --git a/docs/api-docs.md b/docs/api-docs.md index 9da0d5fcea..979fad497b 100644 --- a/docs/api-docs.md +++ b/docs/api-docs.md @@ -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. diff --git a/docs/api-standards.md b/docs/api-standards.md index f507fa1b80..ab395c984a 100644 --- a/docs/api-standards.md +++ b/docs/api-standards.md @@ -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. diff --git a/docs/changelog.md b/docs/changelog.md index 8d464828c7..b8742b64c2 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -3,7 +3,6 @@ toc: maxDepth: 2 --- - # Redocly CLI changelog @@ -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 diff --git a/docs/commands/build-docs.md b/docs/commands/build-docs.md index 4565b2a719..b77bbb5bd3 100644 --- a/docs/commands/build-docs.md +++ b/docs/commands/build-docs.md @@ -27,7 +27,7 @@ redocly build-docs -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 diff --git a/docs/commands/lint.md b/docs/commands/lint.md index c675acc13c..cdf8b9a460 100644 --- a/docs/commands/lint.md +++ b/docs/commands/lint.md @@ -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.
**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.
**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.
**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 @@ -245,6 +271,7 @@ redocly lint --format=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 %} diff --git a/docs/custom-plugins/custom-config.md b/docs/custom-plugins/custom-config.md index fbc40701bf..26e4f6f80e 100644 --- a/docs/custom-plugins/custom-config.md +++ b/docs/custom-plugins/custom-config.md @@ -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 %} - diff --git a/docs/custom-plugins/custom-decorators.md b/docs/custom-plugins/custom-decorators.md index a3ed70e9e0..368d03e277 100644 --- a/docs/custom-plugins/custom-decorators.md +++ b/docs/custom-plugins/custom-decorators.md @@ -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). diff --git a/docs/custom-plugins/custom-rules.md b/docs/custom-plugins/custom-rules.md index a07a91ce2e..d75c168a5d 100644 --- a/docs/custom-plugins/custom-rules.md +++ b/docs/custom-plugins/custom-rules.md @@ -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. - diff --git a/docs/custom-plugins/index.md b/docs/custom-plugins/index.md index 1940d7ebc0..ce24448851 100644 --- a/docs/custom-plugins/index.md +++ b/docs/custom-plugins/index.md @@ -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. - - diff --git a/docs/custom-plugins/visitor.md b/docs/custom-plugins/visitor.md index acdef366fb..431bf27f39 100644 --- a/docs/custom-plugins/visitor.md +++ b/docs/custom-plugins/visitor.md @@ -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 ``` - - diff --git a/docs/decorators/filter-in.md b/docs/decorators/filter-in.md index be74f85e6f..83c1faff8f 100644 --- a/docs/decorators/filter-in.md +++ b/docs/decorators/filter-in.md @@ -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: diff --git a/docs/decorators/filter-out.md b/docs/decorators/filter-out.md index 9cbf8cd540..7acdc4bc9a 100644 --- a/docs/decorators/filter-out.md +++ b/docs/decorators/filter-out.md @@ -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: diff --git a/docs/decorators/info-description-override.md b/docs/decorators/info-description-override.md index 3715655b47..23205ebdc6 100644 --- a/docs/decorators/info-description-override.md +++ b/docs/decorators/info-description-override.md @@ -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 diff --git a/docs/decorators/info-override.md b/docs/decorators/info-override.md index 06e56ce10d..bd91e25f30 100644 --- a/docs/decorators/info-override.md +++ b/docs/decorators/info-override.md @@ -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: diff --git a/docs/decorators/media-type-examples-override.md b/docs/decorators/media-type-examples-override.md index 79fe5149fe..c99993539e 100644 --- a/docs/decorators/media-type-examples-override.md +++ b/docs/decorators/media-type-examples-override.md @@ -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) diff --git a/docs/decorators/operation-description-override.md b/docs/decorators/operation-description-override.md index dee74bf037..54849f4357 100644 --- a/docs/decorators/operation-description-override.md +++ b/docs/decorators/operation-description-override.md @@ -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 diff --git a/docs/decorators/remove-x-internal.md b/docs/decorators/remove-x-internal.md index 5c92be35cd..e158b7734b 100644 --- a/docs/decorators/remove-x-internal.md +++ b/docs/decorators/remove-x-internal.md @@ -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: diff --git a/docs/decorators/tag-description-override.md b/docs/decorators/tag-description-override.md index 9f2db86e74..ed3e608b8a 100644 --- a/docs/decorators/tag-description-override.md +++ b/docs/decorators/tag-description-override.md @@ -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 diff --git a/docs/file-management.md b/docs/file-management.md index 0e4d324d79..26e642ac64 100644 --- a/docs/file-management.md +++ b/docs/file-management.md @@ -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 diff --git a/docs/guides/autocomplete.md b/docs/guides/autocomplete.md index 80b5660127..39d9d6a5e6 100644 --- a/docs/guides/autocomplete.md +++ b/docs/guides/autocomplete.md @@ -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. - diff --git a/docs/guides/change-token-url.md b/docs/guides/change-token-url.md index b21c854318..3eb91c2276 100644 --- a/docs/guides/change-token-url.md +++ b/docs/guides/change-token-url.md @@ -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 %} diff --git a/docs/guides/configure-rules.md b/docs/guides/configure-rules.md index 8ac3158cb9..1ac55c5f88 100644 --- a/docs/guides/configure-rules.md +++ b/docs/guides/configure-rules.md @@ -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. diff --git a/docs/guides/hide-specification-extensions.md b/docs/guides/hide-specification-extensions.md index 4f039d3df0..4968e49865 100644 --- a/docs/guides/hide-specification-extensions.md +++ b/docs/guides/hide-specification-extensions.md @@ -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'; - - const decorators = { - oas3: { - 'hide-openapi-extensions': hideOpenapiExtensions, - }, - }; - - module.exports = { - id, - decorators, - }; - ``` + ```js + const hideOpenapiExtensions = require('./decorators/hide-openapi-extensions'); + const id = 'plugin'; + + const decorators = { + oas3: { + 'hide-openapi-extensions': hideOpenapiExtensions, + }, + }; + + 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; - - /** @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]; - } - }); - }); - } - } - } - } - ``` + ```js + module.exports = hideOpenapiExtensions; + + /** @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]; + } + }); + }); + } + } + } + } + ``` 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 diff --git a/docs/guides/lint-asyncapi.md b/docs/guides/lint-asyncapi.md index b1ddcfc79e..2cf34440f8 100644 --- a/docs/guides/lint-asyncapi.md +++ b/docs/guides/lint-asyncapi.md @@ -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 diff --git a/docs/guides/migrate-from-spectral.md b/docs/guides/migrate-from-spectral.md index 0bbee13402..dab7822917 100644 --- a/docs/guides/migrate-from-spectral.md +++ b/docs/guides/migrate-from-spectral.md @@ -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 diff --git a/docs/guides/migrate-from-swagger-cli.md b/docs/guides/migrate-from-swagger-cli.md index 51cf13ed7a..8094eda3f5 100644 --- a/docs/guides/migrate-from-swagger-cli.md +++ b/docs/guides/migrate-from-swagger-cli.md @@ -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 diff --git a/docs/installation.md b/docs/installation.md index a9b83e350f..efa4458e0c 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -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 [options] ``` + {% /tab %} {% tab label="Example with lint command" %} + ```shell npx @redocly/cli@latest lint petstore.yaml ``` + {% /tab %} {% /tabs %} + ## 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. - diff --git a/docs/quickstart.md b/docs/quickstart.md index 3e79325b9f..8403b63905 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -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 diff --git a/docs/rules.md b/docs/rules.md index c2eecf2a82..fab5d1eded 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -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). diff --git a/docs/rules/boolean-parameter-prefixes.md b/docs/rules/boolean-parameter-prefixes.md index 43d7724fa1..9747995e4e 100644 --- a/docs/rules/boolean-parameter-prefixes.md +++ b/docs/rules/boolean-parameter-prefixes.md @@ -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) diff --git a/docs/rules/component-name-unique.md b/docs/rules/component-name-unique.md index 42d34c7a31..c0926d095f 100644 --- a/docs/rules/component-name-unique.md +++ b/docs/rules/component-name-unique.md @@ -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: diff --git a/docs/rules/info-contact.md b/docs/rules/info-contact.md index d37b53dba3..c2217ade25 100644 --- a/docs/rules/info-contact.md +++ b/docs/rules/info-contact.md @@ -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: diff --git a/docs/rules/info-license-url.md b/docs/rules/info-license-url.md index 8c7736b4a4..6576425b6f 100644 --- a/docs/rules/info-license-url.md +++ b/docs/rules/info-license-url.md @@ -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/) - diff --git a/docs/rules/info-license.md b/docs/rules/info-license.md index cef37d0f5a..3844040377 100644 --- a/docs/rules/info-license.md +++ b/docs/rules/info-license.md @@ -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 diff --git a/docs/rules/minimal.md b/docs/rules/minimal.md index a3eed5d90a..bbc49fddbb 100644 --- a/docs/rules/minimal.md +++ b/docs/rules/minimal.md @@ -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) diff --git a/docs/rules/no-ambiguous-paths.md b/docs/rules/no-ambiguous-paths.md index 09a766d212..16a3271495 100644 --- a/docs/rules/no-ambiguous-paths.md +++ b/docs/rules/no-ambiguous-paths.md @@ -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: diff --git a/docs/rules/no-empty-servers.md b/docs/rules/no-empty-servers.md index 84b8713ac5..3c29b25e36 100644 --- a/docs/rules/no-empty-servers.md +++ b/docs/rules/no-empty-servers.md @@ -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) diff --git a/docs/rules/no-enum-type-mismatch.md b/docs/rules/no-enum-type-mismatch.md index d08dd0a160..163527451f 100644 --- a/docs/rules/no-enum-type-mismatch.md +++ b/docs/rules/no-enum-type-mismatch.md @@ -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: diff --git a/docs/rules/no-example-value-and-externalValue.md b/docs/rules/no-example-value-and-externalValue.md index 6a0d648ac5..567074a2d8 100644 --- a/docs/rules/no-example-value-and-externalValue.md +++ b/docs/rules/no-example-value-and-externalValue.md @@ -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: diff --git a/docs/rules/no-http-verbs-in-paths.md b/docs/rules/no-http-verbs-in-paths.md index 716b3193f1..b785b6b927 100644 --- a/docs/rules/no-http-verbs-in-paths.md +++ b/docs/rules/no-http-verbs-in-paths.md @@ -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/) - diff --git a/docs/rules/no-identical-paths.md b/docs/rules/no-identical-paths.md index 7c24151629..730eec5235 100644 --- a/docs/rules/no-identical-paths.md +++ b/docs/rules/no-identical-paths.md @@ -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) diff --git a/docs/rules/no-invalid-media-type-examples.md b/docs/rules/no-invalid-media-type-examples.md index d44b85e958..bec98235fe 100644 --- a/docs/rules/no-invalid-media-type-examples.md +++ b/docs/rules/no-invalid-media-type-examples.md @@ -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: diff --git a/docs/rules/no-invalid-parameter-examples.md b/docs/rules/no-invalid-parameter-examples.md index 9a3e4c2abe..1a9df49dc2 100644 --- a/docs/rules/no-invalid-parameter-examples.md +++ b/docs/rules/no-invalid-parameter-examples.md @@ -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: diff --git a/docs/rules/no-invalid-schema-examples.md b/docs/rules/no-invalid-schema-examples.md index 337ffb15f0..14c0d1040b 100644 --- a/docs/rules/no-invalid-schema-examples.md +++ b/docs/rules/no-invalid-schema-examples.md @@ -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: diff --git a/docs/rules/no-path-trailing-slash.md b/docs/rules/no-path-trailing-slash.md index 3fa9d0b571..c651619477 100644 --- a/docs/rules/no-path-trailing-slash.md +++ b/docs/rules/no-path-trailing-slash.md @@ -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/) - diff --git a/docs/rules/no-server-example-com.md b/docs/rules/no-server-example-com.md index b6d4a25120..1c572d2db5 100644 --- a/docs/rules/no-server-example-com.md +++ b/docs/rules/no-server-example-com.md @@ -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) diff --git a/docs/rules/no-server-trailing-slash.md b/docs/rules/no-server-trailing-slash.md index 91249e7b79..c1a59e75a0 100644 --- a/docs/rules/no-server-trailing-slash.md +++ b/docs/rules/no-server-trailing-slash.md @@ -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: diff --git a/docs/rules/no-undefined-server-variable.md b/docs/rules/no-undefined-server-variable.md index f6177a2f20..795876af51 100644 --- a/docs/rules/no-undefined-server-variable.md +++ b/docs/rules/no-undefined-server-variable.md @@ -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: diff --git a/docs/rules/no-unresolved-refs.md b/docs/rules/no-unresolved-refs.md index 82ef76c931..9f25fc9579 100644 --- a/docs/rules/no-unresolved-refs.md +++ b/docs/rules/no-unresolved-refs.md @@ -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) - diff --git a/docs/rules/no-unused-components.md b/docs/rules/no-unused-components.md index 88b42b87dc..a1d0cb9880 100644 --- a/docs/rules/no-unused-components.md +++ b/docs/rules/no-unused-components.md @@ -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. diff --git a/docs/rules/operation-2xx-response.md b/docs/rules/operation-2xx-response.md index 417fe3651c..37e02985d7 100644 --- a/docs/rules/operation-2xx-response.md +++ b/docs/rules/operation-2xx-response.md @@ -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: diff --git a/docs/rules/operation-4xx-problem-details-rfc7807.md b/docs/rules/operation-4xx-problem-details-rfc7807.md index 4395035c8d..1f2b14ae98 100644 --- a/docs/rules/operation-4xx-problem-details-rfc7807.md +++ b/docs/rules/operation-4xx-problem-details-rfc7807.md @@ -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`. diff --git a/docs/rules/operation-4xx-response.md b/docs/rules/operation-4xx-response.md index 9b6b5cbda8..f351925541 100644 --- a/docs/rules/operation-4xx-response.md +++ b/docs/rules/operation-4xx-response.md @@ -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) diff --git a/docs/rules/operation-description.md b/docs/rules/operation-description.md index 8d9c9f355d..7b78760b6c 100644 --- a/docs/rules/operation-description.md +++ b/docs/rules/operation-description.md @@ -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: diff --git a/docs/rules/operation-operationId-unique.md b/docs/rules/operation-operationId-unique.md index 1338912ef3..d0924a5f9f 100644 --- a/docs/rules/operation-operationId-unique.md +++ b/docs/rules/operation-operationId-unique.md @@ -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: diff --git a/docs/rules/operation-operationId-url-safe.md b/docs/rules/operation-operationId-url-safe.md index 5be8d472d9..7c159b0dc0 100644 --- a/docs/rules/operation-operationId-url-safe.md +++ b/docs/rules/operation-operationId-url-safe.md @@ -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: diff --git a/docs/rules/operation-operationId.md b/docs/rules/operation-operationId.md index aea6fb0e7c..0f8749d4cc 100644 --- a/docs/rules/operation-operationId.md +++ b/docs/rules/operation-operationId.md @@ -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: diff --git a/docs/rules/operation-parameters-unique.md b/docs/rules/operation-parameters-unique.md index 8308cbfa31..9b75646016 100644 --- a/docs/rules/operation-parameters-unique.md +++ b/docs/rules/operation-parameters-unique.md @@ -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 diff --git a/docs/rules/operation-singular-tag.md b/docs/rules/operation-singular-tag.md index 838acfb0e6..530b560692 100644 --- a/docs/rules/operation-singular-tag.md +++ b/docs/rules/operation-singular-tag.md @@ -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: diff --git a/docs/rules/operation-summary.md b/docs/rules/operation-summary.md index 43eff59c08..1fd3e92c67 100644 --- a/docs/rules/operation-summary.md +++ b/docs/rules/operation-summary.md @@ -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: diff --git a/docs/rules/operation-tag-defined.md b/docs/rules/operation-tag-defined.md index 0a2c54fa71..8698cc972b 100644 --- a/docs/rules/operation-tag-defined.md +++ b/docs/rules/operation-tag-defined.md @@ -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 diff --git a/docs/rules/parameter-description.md b/docs/rules/parameter-description.md index 916d987c3c..96b47ade77 100644 --- a/docs/rules/parameter-description.md +++ b/docs/rules/parameter-description.md @@ -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 diff --git a/docs/rules/path-declaration-must-exist.md b/docs/rules/path-declaration-must-exist.md index 4600d99ead..786a2eafb7 100644 --- a/docs/rules/path-declaration-must-exist.md +++ b/docs/rules/path-declaration-must-exist.md @@ -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 diff --git a/docs/rules/path-excludes-patterns.md b/docs/rules/path-excludes-patterns.md index c3a388cf1f..50b93d5fa1 100644 --- a/docs/rules/path-excludes-patterns.md +++ b/docs/rules/path-excludes-patterns.md @@ -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: diff --git a/docs/rules/path-not-include-query.md b/docs/rules/path-not-include-query.md index 04c8b7f031..e68ee6f116 100644 --- a/docs/rules/path-not-include-query.md +++ b/docs/rules/path-not-include-query.md @@ -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 diff --git a/docs/rules/path-parameters-defined.md b/docs/rules/path-parameters-defined.md index 5b60d7f43d..492ed5f9d8 100644 --- a/docs/rules/path-parameters-defined.md +++ b/docs/rules/path-parameters-defined.md @@ -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 diff --git a/docs/rules/path-segment-plural.md b/docs/rules/path-segment-plural.md index 340e1ffa5b..4adc09d7cc 100644 --- a/docs/rules/path-segment-plural.md +++ b/docs/rules/path-segment-plural.md @@ -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: diff --git a/docs/rules/paths-kebab-case.md b/docs/rules/paths-kebab-case.md index f5cea8257f..0ddf7a9b49 100644 --- a/docs/rules/paths-kebab-case.md +++ b/docs/rules/paths-kebab-case.md @@ -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 diff --git a/docs/rules/recommended.md b/docs/rules/recommended.md index 4c65c0cf1e..8869d0ecb9 100644 --- a/docs/rules/recommended.md +++ b/docs/rules/recommended.md @@ -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 diff --git a/docs/rules/request-mime-type.md b/docs/rules/request-mime-type.md index 467f040f54..e693ead38f 100644 --- a/docs/rules/request-mime-type.md +++ b/docs/rules/request-mime-type.md @@ -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: diff --git a/docs/rules/required-string-property-missing-min-length.md b/docs/rules/required-string-property-missing-min-length.md index 4860647fe3..531eb284fe 100644 --- a/docs/rules/required-string-property-missing-min-length.md +++ b/docs/rules/required-string-property-missing-min-length.md @@ -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: diff --git a/docs/rules/response-contains-header.md b/docs/rules/response-contains-header.md index a15b153aa8..2a8f9f230e 100644 --- a/docs/rules/response-contains-header.md +++ b/docs/rules/response-contains-header.md @@ -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: diff --git a/docs/rules/response-contains-property.md b/docs/rules/response-contains-property.md index a59ad486fe..cf107df9d4 100644 --- a/docs/rules/response-contains-property.md +++ b/docs/rules/response-contains-property.md @@ -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 diff --git a/docs/rules/response-mime-type.md b/docs/rules/response-mime-type.md index fb352d8d98..51b02ade92 100644 --- a/docs/rules/response-mime-type.md +++ b/docs/rules/response-mime-type.md @@ -1,14 +1,14 @@ --- slug: /docs/cli/rules/response-mime-type --- -# response-mime-type -|OAS|Compatibility| -|---|---| -|2.0|✅| -|3.0|✅| -|3.1|✅| +# response-mime-type +| 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: diff --git a/docs/rules/scalar-property-missing-example.md b/docs/rules/scalar-property-missing-example.md index 94d0535730..4fdbc1730e 100644 --- a/docs/rules/scalar-property-missing-example.md +++ b/docs/rules/scalar-property-missing-example.md @@ -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: diff --git a/docs/rules/security-defined.md b/docs/rules/security-defined.md index b8164271cb..b32ce4dd5d 100644 --- a/docs/rules/security-defined.md +++ b/docs/rules/security-defined.md @@ -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 +## 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: diff --git a/docs/rules/spec-components-invalid-map-name.md b/docs/rules/spec-components-invalid-map-name.md index 0fee8e0496..355548271d 100644 --- a/docs/rules/spec-components-invalid-map-name.md +++ b/docs/rules/spec-components-invalid-map-name.md @@ -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: diff --git a/docs/rules/spec-strict-refs.md b/docs/rules/spec-strict-refs.md index 4981214237..790e8fcbca 100644 --- a/docs/rules/spec-strict-refs.md +++ b/docs/rules/spec-strict-refs.md @@ -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. diff --git a/docs/rules/spec.md b/docs/rules/spec.md index a54970a2f7..c7e2d96976 100644 --- a/docs/rules/spec.md +++ b/docs/rules/spec.md @@ -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: diff --git a/docs/rules/tag-description.md b/docs/rules/tag-description.md index c92e8557fb..c5bbe80c6f 100644 --- a/docs/rules/tag-description.md +++ b/docs/rules/tag-description.md @@ -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 diff --git a/docs/rules/tags-alphabetical.md b/docs/rules/tags-alphabetical.md index 17b94ee62b..2edfe261e9 100644 --- a/docs/rules/tags-alphabetical.md +++ b/docs/rules/tags-alphabetical.md @@ -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: diff --git a/docs/usage-data.md b/docs/usage-data.md index f983e9e749..9cd94e3f56 100644 --- a/docs/usage-data.md +++ b/docs/usage-data.md @@ -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.