afb5d9425f
* fix: Remove github token with incorrect access * docs: Improve uninstall CTA in migration guide * fix: Update checkout action version for vale * docs: Vale reports errors in any edited file * docs: Update to make Vale happy * docs: Markdownlint fixes * fix: Remove sync actions as this integration is no longer used * core: Add markdownlint config and github action Uses rules from https://github.com/Redocly/marketing-site-portal/pull/1142 * chore: Move contributing file to top level * chore: Add markdown to the file types that we want prettier to operate on * fix: Make files fit prettier rules, ignore LICENSE since we can't change that * chore: Combine docs-related workflows into one for simplicity * docs: Add instructions for running the CLI docs standalone from this repo * chore: Add changeset, this docs change is quite large * Update .changeset/bright-steaks-walk.md Co-authored-by: Ihor Karpiuk <106662428+IgorKarpiuk@users.noreply.github.com> --------- Co-authored-by: Ihor Karpiuk <106662428+IgorKarpiuk@users.noreply.github.com>
2.5 KiB
Configure your linting rules
Use individual rules to make the API linting fit your API needs. Start with the recommended or minimal ruleset, then adjust as needed.
Set rules and severity
Control the severity of each rule:
error: return an error if this rule isn't satisfiedwarn: report a warning if this rule isn't satisfiedoff: disable this rule
Turn rules on to add them to the existing ruleset, or off if your API doesn't require them. Here's an example:
extends:
- recommended
rules:
info-license: off
path-kebab-case: error
The example removes one of the rules from the recommended ruleset, perhaps because this organization is still working on its standards, and adds another one, path-kebab-case, to ensure consistency of path design.
Find a full list of built-in rules here.
Set rule options
Some rules allow additional configuration. For example, the rule boolean-parameter-prefixes supports an array of prefixes (see rule documentation). To set these in a configuration file, set the rule severity and any options within the rule configuration, like this:
rules:
boolean-parameter-prefixes:
severity: error
prefixes: ['can', 'is', 'has']
Configurable rules
Configurable rules are your opportunity to customize the exact rules your API needs, by describing the conditions that the various API description fields should meet. Declare these alongside the built-in rules in your configuration file:
rules:
info-license: off
rule/big-tag-name:
subject:
type: Tag
property: name
assertions:
defined: true
casing: MACRO_CASE
severity: warn
message: Tag names must be upper case with underscores (_).
Visit the configurable rules page for more detailed documentation and many more examples.
Rules from custom plugins
If you create your own rules in custom plugins, you can add these in the rules section of redocly.yaml. Make sure to import the plugin first, and then refer to the rule name prefixed with the plugin name:
plugins:
- './my-best-plugin.js'
rules:
my-best-plugin/rule1: error
It's recommended to use the built-in or configurable rules to meet your linting needs if possible, but the custom plugins can offer additional functionality or advanced logic if needed.