Spectral offers similar linting capabilities to Redocly CLI and the rest of the Redocly tools. This guide lays out the differences so you can switch tools if you want to.
The first step is to install Redocly CLI.
Replace spectral lint openapi.yaml with the equivalent redocly command:
redocly lint openapi.yamlFor more information, check out the lint command documentation.
Instead of --ruleset/-r, use the --extends parameter to indicate which ruleset you are using as a basis.
Read more about linting and rulesets
Similar to Spectral, Redocly offers multiple output formats using the --format parameter.
If you use --resolver to handle how links and remote URLs are resolved, visit the configuration documentation to see how to handle this with Redocly.
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.
- Add configuration for the rules accordingly. They can be set to error, warn, or off.
- Expand the collection with any configurable rules that fit your standard.
Below is an example of a redocly.yaml configuration file, enabling the minimal ruleset, disabling the security-defined rule, and setting up an example configurable rule to check for the word "test" appearing in an operation summary.
extends:
- minimal
rules:
security-defined: off
rule/naming:
subject:
type: Operation
property: summary
assertions:
notPattern: /test/
message: "Operation summary must not include the word test"It is also possible to configure additional rules for specific APIs using the APIs object to set per-API rules (or exceptions!).
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?
| Spectral rules | Redocly rules |
|---|---|
duplicated-entry-in-enum | |
info-contact | info-contact |
info-description | |
info-license | info-license |
license-url | info-license-strict |
no-$ref-siblings | |
no-eval-in-markdown | |
no-script-tags-in-markdown | |
oas3-api-servers | no-empty-servers |
oas3-examples-value-or-externalValue | no-example-value-and-externalValue |
oas3-operation-security-defined | security-defined |
oas3-parameter-description | parameter-description |
oas3-schema | struct |
oas3-server-not-example.com | no-server-example.com |
oas3-server-trailing-slash | no-server-trailing-slash |
oas3-unused-component | no-unused-components |
oas3-valid-media-example | no-invalid-media-type-examples |
oas3-valid-schema-example | no-invalid-schema-examples |
openapi-tags | |
openapi-tags-alphabetical | tags-alphabetical |
openapi-tags-uniqueness | no-duplicated-tag-names |
operation-description | operation-description |
operation-operationId | operation-operationId |
operation-operationId-unique | operation-operationId-unique |
operation-operationId-valid-in-url | operation-operationId-url-safe |
operation-parameters | operation-parameters-unique |
operation-singular-tag | operation-singular-tag |
operation-success-response | operation-2xx-response |
operation-tag-defined | operation-tag-defined |
operation-tags | |
path-declarations-must-exist | path-declaration-must-exist |
path-keys-no-trailing-slash | no-path-trailing-slash |
path-not-include-query | path-not-include-query |
path-params | path-parameters-defined |
tag-description | tag-description |
typed-enum | no-enum-type-mismatch |
boolean-parameter-prefixes | |
no-ambiguous-paths | |
no-http-verbs-in-paths | |
no-identical-paths | |
no-invalid-parameter-examples | |
no-server-variables-empty-enum | |
no-undefined-server-variable | |
no-unresolved-refs | |
operation-4xx-problem-details-rfc7807 | |
operation-4xx-response | |
operation-summary | |
path-segment-plural | |
paths-kebab-case | |
request-mime-type | |
required-string-property-missing-min-length | |
response-contains-header | |
response-contains-property | |
response-mime-type | |
scalar-property-missing-example | |
spec-components-invalid-map-name |
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. 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
- adding per-API additions or exceptions as required
- using an ignore file to overlook existing/historic incompatibilities while still enforcing rules for changed elements
For some advanced use cases, the configurable rules can't cover all possibilities. If that happens, Redocly supports adding rules in custom plugins so that you can use JavaScript to express any specialist rules you need.
Redocly CLI supports multiple Redocly products and functions, so go ahead and read more about Redocly CLI.