LukeParke/redocly-cli
1
0
Fork 0
mirror of https://github.com/LukeHagar/redocly-cli.git synced 2025-12-06 04:21:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add cli config reference (#1483)

Browse Source 
* docs: Add resolve config reference

* docs: Start API reference, needs child config entries

* docs: Add sidebar entries for config reference pages

* docs: Add rules and decorators config pages

* docs: Fix links and format

* docs: Fix links and formatting

* docs: Add extends and plugins config reference pages

* docs: Add a basic preprocessor page

* docs: Update from review feedback

* Apply suggestions from code review

Co-authored-by: Heather Cloward <heathercloward@gmail.com>

* docs: Reformat required labels

* Apply suggestions from code review

Co-authored-by: Heather Cloward <heathercloward@gmail.com>

* docs: Fix misspelling

---------

Co-authored-by: Heather Cloward <heathercloward@gmail.com>
This commit is contained in:
Lorna Jane Mitchell
2024-03-26 09:49:17 +00:00
committed by GitHub
parent a7299534a3
commit 17b73c1723
9 changed files with 495 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/configuration/index.md
View File

@@ -213,7 +213,7 @@ Redocly CLI supports one `http` header per URL.
Here is an example for adding header definitions:
```yaml
```text
resolve:
http:
headers:

85
docs/configuration/reference/apis.md Normal file
View File

@@ -0,0 +1,85 @@
# `apis`
## Introduction
If your project contains multiple APIs, the `apis` configuration section allows you to set up different rules and settings for different APIs.
## Options
{% table %}
- Option
- Type
- Description
---
- `{name}@{version}`
- [API object](#api-object)
- **REQUIRED**. Each API needs a name and optionally a version. Supports alphanumeric characters and underscores.
{% /table %}
### API object
{% table %}
- Option
- Type
- Description
---
- root
- string
- **REQUIRED**. Path to the root API description file.
---
- rules
- [Rules object](./rules.md)
- Additional rule configuration for this API.
---
- decorators
- [Decorators object](./decorators.md)
- Additional decorator configuration for this API.
---
- preprocessors
- [Decorators object](./decorators.md)
- Preprocessors run before linting, and follow the same structure as decorators. We recommend the use of decorators over preprocessors in most cases.
{% /table %}
## Examples
The following example shows a simple `redocly.yaml` configuration file with settings for multiple APIs.
```yaml
apis:
orders@v3:
root: orders/openapi.yaml
rules:
tags-alphabetical: error
operation-operationId-unique: error
spec-strict-refs: error
newsletter:
root: newsletter/openapi.yaml
rules:
info-contact: off
operation-summary: off
```
## Related options
- [extends](./extends.md) sets the base ruleset to use.
- [rules](./rules.md) settings define the linting rules that are used.
- [decorators](./decorators.md) offer some transformations for your OpenAPI documents.
## Resources
- More information and examples of [per-API configuration](../apis.md).
- List of [built-in rules](../../rules/built-in-rules.md).

91
docs/configuration/reference/decorators.md Normal file
View File

@@ -0,0 +1,91 @@
# `decorators`
## Introduction
The `decorators` configuration section defines the transformation steps that are applied to your API description when it is bundled.
Both the [built-in decorators](../../decorators.md) and [decorators from custom plugins](../../custom-plugins/custom-decorators.md) are configured in this section.
The `decorators` block can be used at the root of a configuration file, or inside an [API-specific section](./apis.md).
## Options
{% table %}
- Option
- Type
- Description
---
- {decorator name}
- string _or_ [Decorator object](#decorator-object)
- **REQUIRED**. You can add as many decorators as you wish. The keys must be either built-in decorators (for example `info-description-override`), or a decorator from a plugin (for example `tags-plugin/no-unused-tags`). Set the value to `on` or `off` to enable or disable a decorator, or use a [Decorator object](#decorator-object) to configure additional options for a specific decorator.
{% /table %}
### Decorator object
{% table %}
- Option
- Type
- Description
---
- {additional properties}
- any
- Some decorators support additional configuration, check the documentation for each specific decorator to discover the values that can be used. For example the [`filter-out` decorator](../../decorators/filter-out.md) supports `property` and `value` settings for what to filter.
---
- severity
- string
- Severity level of any problems reported with this decorator. Setting this option is usually only useful for troubleshooting purposes. The value must be one of `error`, `warn`, or `off`, where `off` disables the decorator.
{% /table %}
## Examples
This section covers some examples and common use cases.
### Configure built-in decorators
Pick and mix the built-in decorators in your `redocly.yaml` file as you need to.
The following example enables the `remove-unused-components` decorator, and uses `info-override` to update the title:
```yaml
decorators:
remove-unused-components: on
info-override:
title: Better title than before
```
The `info-override` decorator accepts some additional configuration.
### Configure decorators from custom plugins
Redocly also supports [custom plugins](../../custom-plugins/custom-rules.md) for advanced users.
Decorators in custom plugins are also configured in the `decorators` section of the configuration file, using the plugin's module name as a prefix.
The following example shows enabling a decorator called `alphabetical` from a plugin named `tag-sorting`:
```yaml
plugins:
- './tag-sorting.js'
decorators:
tag-sorting/alphabetical: on
```
The example includes adding the plugin, partly to remind you that this is also needed.
## Related options
- [apis](./apis.md) configuration options allow setting per-API configuration in `redocly.yaml`.
- [rules](./rules.md) settings define the linting rules that are used.
## Resources
- Learn more about [decorators](../../decorators.md).
- To build your own decorators, you can use [custom plugins](../../custom-plugins/index.md).
- The [Redocly CLI cookbook](https://github.com/Redocly/redocly-cli-cookbook) is a great resource for learning and sharing decorators and custom plugins.

41
docs/configuration/reference/extends.md Normal file
View File

@@ -0,0 +1,41 @@
# `extends`
## Introduction
The `extends` configuration entry allows your project configuration to extend an existing configuration set.
Multiple values are supported, and can include:
- the name of a [built-in ruleset](../../rules.md#rulesets)
- configuration defined in a [custom plugin](../../custom-plugins/index.md)
- a path or URL to another `redocly.yaml` file
Extends is useful if you use a common ruleset across multiple projects.
Define a ruleset in one location, and each project can `extend` it, with or without modification.
{% admonition type="info" name="Default ruleset: recommended" %}
If there is no `redocly.yaml` configuration file, the [recommended ruleset](../../rules/recommended.md) is used by default.
{% /admonition %}
## Options
The `extends` configuration is an array of strings.
The array is parsed in the order it is defined, so the later entries in the array overwrite the earlier ones.
## Examples
To get started, try the following example to configure your project to be based on the [minimal ruleset](../../rules/minimal.md):
```yaml
extends:
- minimal
```
## Related options
- [apis](./apis.md) configuration options allow setting per-API configuration in `redocly.yaml`.
- [rules](./rules.md) settings define the linting rules that are used.
## Resources
- Detailed documentation and examples on [extending configuration](../extends.md).

34
docs/configuration/reference/plugins.md Normal file
View File

@@ -0,0 +1,34 @@
# `plugins`
## Introduction
Redocly supports [custom plugins](../../custom-plugins/index.md) for extending lint and decorator behavior.
Use plugins when you need to add rules beyond the [built-in](../../rules/built-in-rules.md) and [configurable](../../rules/configurable-rules.md), or decorators beyond the [built-in decorators](../../decorators.md).
## Options
The `plugins` configuration is an array of paths to plugin files, relative to the config file.
You can include as many plugins as you need.
## Examples
A basic example of including two plugins from a directory named `plugins/` is shown in the example below:
```yaml
plugins:
- plugins/my-best-plugin.js
- plugins/another-plugin.js
```
Remember that you need to include plugins in the `plugins` section before you can use the content of the plugin elsewhere in the configuration file.
## Related options
- [apis](./apis.md) configuration options allow setting per-API configuration in `redocly.yaml`.
- [rules](./rules.md) settings define the linting rules that are used.
- [decorators](./decorators.md) offer some transformations for your OpenAPI documents.
## Resources
- The [Redocly CLI cookbook](https://redocly.com/blog/redocly-cli-cookbook/) has many examples of plugins.
- Read more [configuration examples](../index.md).

16
docs/configuration/reference/preprocessors.md Normal file
View File

@@ -0,0 +1,16 @@
# `preprocessors`
## Introduction
Preprocessors are similar to decorators, but they run before linting rather than after.
Refer to the [`decorator` configuration options](./decorators.md) documentation for details; the options available are the same in both the `decorators` and `preprocessor` sections of the configuration file.
## Related options
- [decorators](./decorators.md) offer some transformations for your OpenAPI documents.
- [plugins](./plugins.md) allow code extensions to extend the existing functionality.
## Resources
- [Custom plugins](../../custom-plugins/index.md) offer a way to extend the functionality of Redocly.

90
docs/configuration/reference/resolve.md Normal file
View File

@@ -0,0 +1,90 @@
# `resolve`
## Introduction
The `resolve` configuration provides options for how URLs in API descriptions are handled.
If a URL is not publicly accessible, use these configuration settings to add the needed details to gain access.
{% admonition type="info" %}
One HTTP header is supported for each URL resolved.
{% /admonition %}
## Options
{% table %}
- Option
- Type
- Description
---
- doNotResolveExamples
- boolean
- When running `lint`, set this option to `true` to avoid resolving `$ref` fields in examples. Resolving `$ref`s in other parts of the API is unaffected.
---
- http
- [HTTP object](#http-object)
- Describe URL patterns and the corresponding headers to use when resolving references that point to them.
{% /table %}
### HTTP object
{% table %}
- Option
- Type
- Description
---
- matches
- string
- **REQUIRED**. The URL pattern to match, for example `https://api.example.com/v2/**` or `https://example.com/*/test.yaml`.
---
- name
- string
- **REQUIRED**. The header name, for example `Authorization`.
---
- value
- string
- The value to send for the header. Only one of `value` or `envVariable` can be used; `envVariable` is recommended for any secrets.
---
- envVariable
- string
- The name of the environment variable that contains the value to send for the header. Only one of `value` or `envVariable` can be used; `envVariable` is recommended for any secrets.
{% /table %}
## Examples
If you have multiple examples to resolve, you can describe multiple entries with patterns to match and headers to include.
The following example shows two patterns, with the names of environment variables that contain the values to use.
```text
resolve:
http:
headers:
- matches: https://api.example.com/v2/**
name: X-API-KEY
envVariable: SECRET_KEY
- matches: https://example.com/*/test.yaml
name: Authorization
envVariable: SECRET_AUTH
```
When the OpenAPI description references a URL that matches these patterns, it is resolved using the additional header specified.
## Resources
- [Configuration for Redocly CLI](../index.md).
- [How to use `$ref` in OpenAPI](https://redocly.com/docs/resources/ref-guide/).

128
docs/configuration/reference/rules.md Normal file
View File

@@ -0,0 +1,128 @@
# `rules`
## Introduction
The `rules` configuration blocks configure linting rules and their severity.
Configure [built-in rules](../../rules/built-in-rules.md) included by default, [configurable rules](../../rules/configurable-rules.md) you add yourself, and [rules from plugins](../../custom-plugins/custom-rules.md).
The `rules` block can be used at the root of a configuration file, or inside an [API-specific section](./apis.md).
## Options
{% table %}
- Option
- Type
- Description
---
- {rule name}
- [Rule object](#rule-object)
- **REQUIRED**. Add as many rule entries as you like. These keys must be built-in rules (for example `security-defined`), configurable rules that you declare here (for example `rule/my-custom-rule`), or a rule from a plugin (for example `my-plugin/add-awesome`).
{% /table %}
### Rule object
{% table %}
- Option
- Type
- Description
---
- severity
- string
- Severity level of this rule. Must be one of `error`, `warn`, or `off`.
---
- {additional properties}
- any
- Some rules allow additional configuration, check the details of each rule to find out the values that can be supplied here. For example the [`boolean-parameter-prefixes` rule](../../rules/boolean-parameter-prefixes.md) supports an additional option of `prefixes` that accepts an array of strings.
{% /table %}
## Examples
This section covers some examples and common use cases.
### Use shorthand format
When the only configuration needed for a rule is the severity, you can set this as the value for the rule.
The example below sets the `tag-description` rule to `error`:
```yaml
rules:
tag-description: error
```
This shorter syntax can help to keep your configuration file more readable.
### Configure built-in rules
It's rare for our default rulesets to perfectly fit your project.
Adjust the severity level of the rules to suit your needs, so that you can have certainty about the quality of your APIs.
The following example shows some rules configuration:
```yaml
rules:
info-license: error
no-ambiguous-paths: error
boolean-parameter-prefixes:
severity: error
prefixes:
- is
- can
```
All the rules are configured to produce errors if their criteria are not met, the first two use the shorthand syntax to configure the severity of the rule since no other options are needed for those rules.
The `boolean-parameter-prefixes` rule also accepts a list of allowed prefixes, and those are also configured in the example.
### Configure your own rules
Redocly supports [configurable rules](../../rules/configurable-rules.md), and those are configured in the config file.
A rule to check that all `operationId` fields are in camel case is shown in the following example:
```yaml
rules:
rule/operationId-casing:
subject:
type: Operation
property: operationId
assertions:
casing: camelCase
```
The configurable rules have user-defined names that all start with `rule/` and then a meaningful name.
Read the [configurable rules documentation](../../rules/configurable-rules.md) for all the details on what configurable rules can do and how to to use them.
### Configure rules from custom plugins
Redocly also supports [custom plugins](../../custom-plugins/custom-rules.md) for advanced users.
Those are also configured in the `rules` section of the configuration file, using the plugin's module name as a prefix.
The following example shows how to enable a rule named `validate` from a plugin called `openapi-markdown`:
```yaml
plugins:
- './openapi-markdown.js'
rules:
openapi-markdown/validate: warn
```
The example includes an example of including the plugin in your configuration.
## Related options
- [apis](./apis.md) configuration options allow setting per-API configuration in `redocly.yaml`.
- [decorators](./decorators.md) offer some transformations for your OpenAPI documents.
## Resources
- The [Redocly CLI cookbook](https://github.com/Redocly/redocly-cli-cookbook) is a great resource for configurable rules, plugins, and other examples.
- Learn more about [rules](../../rules.md) overall.
- Read the [documentation for configurable rules](../../rules/configurable-rules.md).

9
docs/sidebars.yaml
View File

@@ -140,6 +140,15 @@
- page: configuration/extends.md
- page: configuration/rules.md
- page: configuration/apis.md
- group: Reference
items:
- page: configuration/reference/apis.md
- page: configuration/reference/decorators.md
- page: configuration/reference/extends.md
- page: configuration/reference/plugins.md
- page: configuration/reference/preprocessors.md
- page: configuration/reference/resolve.md
- page: configuration/reference/rules.md
- group: Custom plugins
page: custom-plugins/index.md
items: