-
-
Notifications
You must be signed in to change notification settings - Fork 240
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* docs: include 2.x/3.x to 4.0 migration guide (#381) * docs: include 2.x/3.x to 4.0 migration guide * cleaned up migration guide * remove periods for consistency * docs: feedback from @philsturgeon * docs: cover recommended property * clearing a few things up * Update 4.0.md * fix typo * Documentation Rewrite (#417) New documentation covering CLI and JS APIs, rulesets, workflows, core rules, etc.
- Loading branch information
Phil Sturgeon
authored
Aug 8, 2019
1 parent
b1efa84
commit 5ac0a30
Showing
16 changed files
with
628 additions
and
423 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
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,23 @@ | ||
| # Concepts | ||
|
|
||
| The power of integrating linting into the design-first workflow, or any workflow which involves API descriptions, is often overlooked. | ||
|
|
||
| Linting is not just about checking to see if you OpenAPI or JSON Schema documents are technically correct according to the specifications, they are for enforcing style guides! These style guides, much like eslint, can help catch a lot more than just "invalid syntax". | ||
|
|
||
| To achieve this functionality, Spectral has three key concepts: "Rulesets", "Rules", and "Functions". | ||
|
|
||
| - **Rulesets** act as a container for rules and functions. | ||
| - **Rules** filter your object down to a set of target values, and specify the function that is used to evaluate those values. | ||
| - **Functions** accept a value and return issue(s) if the value is incorrect. | ||
|
|
||
| Rules can be comprised of one of more functions, to facilitate any style guide. | ||
|
|
||
| - HTTP Basic is not allowed at this company | ||
| - Are all operations secured with a security schema | ||
| - Descriptions must not contain Markdown | ||
| - Tags must be plural | ||
| - Tags must be singular | ||
|
|
||
| Spectral comes bundled with a [bunch of functions](../reference/functions.md) and a default style guide for [OpenAPI v2 and v3](./openapi.md), which you can extend, cherry-pick, or disable entirely. | ||
|
|
||
| Learn more about [rulesets](./rulesets.md). |
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,38 @@ | ||
|
|
||
| # Installation | ||
|
|
||
| For many, the easiest way to install Spectral is as a node module. | ||
|
|
||
| ```bash | ||
| npm install -g @stoplight/spectral | ||
| ``` | ||
|
|
||
| If you are a Yarn user: | ||
|
|
||
| ```bash | ||
| yarn global add @stoplight/spectral | ||
| ``` | ||
|
|
||
| ## Executable binaries | ||
|
|
||
| For users without Node and/or NPM/Yarn, we provide standalone packages for [all major platforms](https://github.com/stoplightio/spectral/releases). The quickest way to install the appropriate package for your operating system is via this shell script: | ||
|
|
||
| ```bash | ||
| curl -L https://raw.githack.com/stoplightio/spectral/master/install.sh | sh | ||
| ``` | ||
|
|
||
| Note, the binaries do _not_ auto-update, so you will need to run it again to install new versions. | ||
|
|
||
| ## Docker | ||
|
|
||
| Spectral is also available as a Docker image, which can be handy for all sorts of things, like if you're contributing code to Spectral, want to integrate it into your CI build. | ||
|
|
||
| ```bash | ||
| docker run --rm -it stoplight/spectral lint "${url}"` | ||
| ``` | ||
|
|
||
| If the file you want to lint is on your computer, you'll need to mount the directory where the file resides as a volume | ||
| ```bash | ||
| docker run --rm -it -v $(pwd):/tmp stoplight/spectral lint "/tmp/file.yaml" | ||
| ``` |
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,7 @@ | ||
| # OpenAPI Support | ||
|
|
||
| Spectral is a generic linter, but a lot of effort has been put in to making sure OpenAPI is well supported. | ||
|
|
||
| Run Spectral against a document without specifying a ruleset will trigger an auto-detect, where Spectral will look to see if `swagger: 2.0` or `openapi: 3.0.x` is at the top of the file. If it finds either of those it will load `spectral:oas2` or `spectral:oas3`, both of which are documented in our [Reference > OpenAPI Rules](../reference/openapi-rules.md). | ||
|
|
||
| _**Note:** If you would like support for other API description formats like RAML, message formats like JSON:API, or anything at all, we recommend you start building up custom, but generic rulesets that can be shared with others. These can then be shared around in a sort of marketplace in the future._ |
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,147 @@ | ||
| # Spectral Rulesets | ||
|
|
||
| Rulesets are collections of rules, in a YAML or JSON file. These rules are taking parameters, and calling functions on certain parts of another YAML or JSON object being linted. | ||
|
|
||
| ### Adding a rule | ||
|
|
||
| Add your own rules under the `rules` property in your `.spectral.yml` ruleset file. | ||
|
|
||
| ```yaml | ||
| rules: | ||
| my-rule-name: | ||
| description: Tags must have a description. | ||
| given: $.tags[*] | ||
| severity: error | ||
| then: | ||
| field: description | ||
| function: truthy | ||
| ``` | ||
| The example above adds a single rule that checks that tags objects have a description property defined. | ||
| Running `spectral lint` on the following object with the ruleset above will result in an error being reported, since the tag does not have a description: | ||
|
|
||
| ```json | ||
| { | ||
| "tags": [{ | ||
| "name": "animals" | ||
| }] | ||
| } | ||
| ``` | ||
|
|
||
| While running it with this object, it will succeed: | ||
|
|
||
| ```json | ||
| { | ||
| "tags": [{ | ||
| "name": "animals", | ||
| "description": "come in all shapes and sizes" | ||
| }] | ||
| } | ||
| ``` | ||
|
|
||
| ### Severity | ||
|
|
||
| The `severity` keyword is optional and can be `error`, `warn`, `info`, or `hint`. | ||
|
|
||
| ### Then | ||
|
|
||
| The Then part of the rules explains what to do with the `given` JSON Path, and involves two required keywords: | ||
|
|
||
| ```yaml | ||
| then: | ||
| field: description | ||
| function: truthy | ||
| ``` | ||
|
|
||
| The `field` keyword is optional, and is for applying the function to a specific property in an object. If omitted the function will be applied to the entire target of the `given` JSON Path. The value can also be `@key` to apply the rule to a keys of an object. | ||
|
|
||
| ```yaml | ||
| given: '$.responses' | ||
| then: | ||
| field: '@key' | ||
| function: pattern | ||
| functionOptions: | ||
| match: '^[0-9]+$' | ||
| ``` | ||
|
|
||
| The above pattern based rule would error on `456avbas` as it is not numeric. | ||
|
|
||
| ```yaml | ||
| responses: | ||
| 123: | ||
| foo: bar | ||
| 456avbas: | ||
| foo: bar | ||
| ``` | ||
|
|
||
| ### Extending Rules | ||
|
|
||
| Rulesets can extend other rulesets. For example, Spectral comes with two built in rulesets - one for OpenAPI v2 (`spectral:oas2`), and one for OpenAPI v3 (`spectral:oas3`). | ||
|
|
||
| Use the `extends` property in your ruleset file to build upon or customize other rulesets. | ||
|
|
||
| ```yaml | ||
| extends: spectral:oas2 | ||
| rules: | ||
| my-rule-name: | ||
| description: Tags must have a description. | ||
| given: $.tags[*] | ||
| then: | ||
| field: description | ||
| function: truthy | ||
| ``` | ||
|
|
||
| The example above will apply the core rules from the built in OpenAPI v2 ruleset AND apply the custom `my-rule-name` rule. | ||
|
|
||
| Extends can be a single string or an array of strings, and can contain either local file paths or URLs. | ||
|
|
||
| ```yaml | ||
| extends: | ||
| - ./config/spectral.json | ||
| - https://example.org/api/style.yaml | ||
| ``` | ||
|
|
||
| ### Enable Rules | ||
|
|
||
| Sometimes you might want to apply specific rules from another ruleset. Use the `extends` property, and pass `off` as the second argument in order to add the rules from another ruleset, but disable them all by default. This allows you to pick and choose which rules you would like to enable. | ||
|
|
||
| ```yaml | ||
| extends: [[spectral:oas2, off]] | ||
| rules: | ||
| # This rule is defined in the spectral:oas2 ruleset. We're passing `true` to turn it on and inherit the severity defined in the spectral:oas2 ruleset. | ||
| operation-operationId-unique: true | ||
| ``` | ||
| The example above will run the single rule that we enabled, since we passed `off` to disable all rules by default when extending the `spectral:oas2` ruleset. | ||
|
|
||
| ### Disable Rules | ||
|
|
||
| This example shows the opposite of the "Enabling Specific rules" example. Sometimes you might want to enable all rules by default, and disable a few. | ||
|
|
||
| ```yaml | ||
| extends: [[spectral:oas2, all]] | ||
| rules: | ||
| operation-operationId-unique: false | ||
| ``` | ||
|
|
||
| The example above will run all of the rules defined in the `spectral:oas2` ruleset (rather than the default behavior that runs only the recommended ones), with one exceptions - we turned `operation-operationId-unique` off. | ||
|
|
||
| The current recommended rules are marked with the property `recommended: true` in their respective rulesets: | ||
|
|
||
| - [Rules relevant to both OpenAPI v2 and v3](https://github.com/stoplightio/spectral/tree/master/src/rulesets/oas/index.json) | ||
| - [Rules specific to only OpenAPI v2](https://github.com/stoplightio/spectral/tree/master/src/rulesets/oas2/index.json) | ||
| - [Rules specific to only OpenAPI v3](https://github.com/stoplightio/spectral/tree/master/src/rulesets/oas3/index.json) | ||
|
|
||
| ### Changing Severity of a Rule | ||
|
|
||
| ```yaml | ||
| extends: spectral:oas2 | ||
| rules: | ||
| operation-2xx-response: warn | ||
| ``` | ||
|
|
||
| The example above will run the recommended rules from the `spectral:oas2` ruleset, but report `operation-2xx-response` as a warning rather than as an error (as is the default behavior in the `spectral:oas2` ruleset). | ||
|
|
||
| Available severity levels are `error`, `warn`, `info`, `hint`, and `off`. |
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
Oops, something went wrong.