-
Notifications
You must be signed in to change notification settings - Fork 148
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Docs for migrating from Spectral to Redocly CLI (#1131)
* docs: Draft of spectral migration guide * docs: add redocly and spectral rules list * docs: fix configurable rule example and some links, add a punchline * docs: Expand on the custom and configurable rules options * fix: a broken link
- Loading branch information
Showing
1 changed file
with
144 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,144 @@ | ||
| # Migrate to Redocly from Spectral | ||
|
|
||
| [Spectral](https://stoplight.io/open-source/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](../installation.md). | ||
|
|
||
| ## Update command | ||
|
|
||
| Replace `spectral lint openapi.yaml` with the equivalent `redocly` command: | ||
|
|
||
| ```yaml | ||
| redocly lint openapi.yaml | ||
| ``` | ||
|
|
||
| For more information, check out the [`lint` command documentation](../commands/lint.md). | ||
|
|
||
| ### Specify ruleset | ||
|
|
||
| Instead of `--ruleset`/`-r`, use the `--extends` parameter to indicate which ruleset you are using as a basis. | ||
|
|
||
| Read more [about linting and rulesets](../api-standards.md) | ||
|
|
||
| ### Choose output format | ||
|
|
||
| Similar to Spectral, Redocly offers multiple output formats using the `--format` parameter. | ||
|
|
||
| ### Resolvers | ||
|
|
||
| If you use `--resolver` to handle how links and remote URLs are resolved, visit the [configuration documentation](../../configuration.md/#resolve-object) to see how to handle this with Redocly. | ||
|
|
||
| ## Update configuration | ||
|
|
||
| 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. | ||
|
|
||
| ### Example Redocly configuration file | ||
|
|
||
| Below is an example of a `redocly.yaml` configuration file, enabling the [minimal ruleset](../rules/minimal.md), disabling the `security-defined` rule, and setting up an example [configurable rule](../rules/configurable-rules.md) to check for the word "test" appearing in an operation summary. | ||
|
|
||
| ```yaml | ||
| 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](../../configuration.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` | | | ||
| | `info-license` | `info-license` | | ||
| | `license-url` | `info-license-url` | | ||
| | `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` | `spec` | | ||
| | `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` | | | ||
| | `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` | | | ||
| | | `boolean-parameter-prefixes` | | ||
| | | `no-ambiguous-paths` | | ||
| | | `no-enum-type-mismatch` | | ||
| | | `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-excludes-patterns` | | ||
| | | `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` | | ||
|
|
||
| ### Configurable and extensible 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 | ||
| - 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](../resources/custom-plugins.md#rules-in-plugins) so that you can use JavaScript to express any specialist rules you need. | ||
|
|
||
| ## Explore tool functionality | ||
|
|
||
| Redocly CLI supports multiple Redocly products and functions, so go ahead and [read more about Redocly CLI](../index.mdx). |
50d699dThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Coverage report
Test suite run success
616 tests passing in 89 suites.
Report generated by 🧪jest coverage report action from 50d699d