Merge branch 'develop' into asyncapi/refs-validation

docs/getting-started/1-concepts.md

@@ -10,11 +10,11 @@ To achieve this, Spectral has three key concepts:
 
 Spectral comes bundled with a [set of core functions](../reference/functions.md) and rulesets for working with [OpenAPI v2 and v3](./4-openapi.md) and [AsyncAPI v2](./5-asyncapi.md) that you can chose to use or extend, but Spectral is about far more than just checking your OpenAPI/AsyncAPI documents are valid.
 
-By far the most popular use-case of Spectral is automating [API Style Guides](https://stoplight.io/api-style-guides-guidelines-and-best-practices?utm_source=github&utm_medium=spectral&utm_campaign=docs), implementing rules that your Architecture, DevOps, API Governance or "Center of Excellence" teams have decided upon. Companies generally write these style guides as wiki pages, and loads can be found on [API Style Book.com](http://apistylebook.com/), but most of these rules could be automated with Spectral.
+By far the most popular use-case of Spectral is automating [API Style Guides](https://stoplight.io/api-style-guides-guidelines-and-best-practices?utm_source=github&utm_medium=spectral&utm_campaign=docs), implementing rules that your Architecture, DevOps, API Governance or "Center of Excellence" teams have decided upon. Companies generally write these style guides as wiki pages, and several can be found on [API Stylebook](http://apistylebook.com/), but most of these rules could be automated with Spectral.
 
 - Paths must be `/kebab-case` ([more ideas for URL rules](https://blog.stoplight.io/consistent-api-urls-with-openapi-and-style-guides))
 - HTTP Basic is not allowed at this company
-- Restrict use of numeric integers in favor of UUID or whatever other ID patter you pick
+- Restrict the use of numeric integers in favor of UUID or any other ID pattern you choose
 - Enforce consistent hypermedia formats, like [JSON:API], or [another format](https://sookocheff.com/post/api/on-choosing-a-hypermedia-format/).
 
 To do that, you'll want to learn a bit more about how rulesets work.

docs/getting-started/2-installation.md

@@ -1,38 +1,39 @@
 # Installation
 
-For many, the easiest way to install Spectral is as a node module.
+You can install Spectral using [npm](https://www.npmjs.com/):
 
 ```bash
 npm install -g @stoplight/spectral-cli
 ```
 
-If you are a Yarn user:
+Or if you are a [Yarn](https://yarnpkg.com/) user:
 
 ```bash
 yarn global add @stoplight/spectral-cli
 ```
 
 ## 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:
+For users without Node.js 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.github.com/stoplightio/spectral/master/scripts/install.sh | sh
 ```
 
-Note, the binaries do _not_ auto-update, so you will need to run it again to install new versions.
+The binaries do _not_ auto-update, so you will need to run the command 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.
-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
+Spectral is also available as a Docker image, which can be useful if you're contributing code to Spectral, or you want to integrate it into your CI build, among other things.
+
+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
 # make sure to update the value of `--ruleset` according to the actual location of your ruleset
 docker run --rm -it -v $(pwd):/tmp stoplight/spectral lint --ruleset "/tmp/.spectral.js" "/tmp/file.yaml"
 ```
 
-To use the docker image on GitLab you need to set `entrypoint` to `""` like this
+To use the docker image on GitLab you need to set `entrypoint` to `""` like this:
 
 ```yml
 stages:

docs/getting-started/3-rulesets.md

@@ -15,7 +15,7 @@ Rules might look a bit like this:
 ```yaml
 rules:
   paths-kebab-case:
-    description: Should paths be kebab-case.
+    description: Paths should be kebab-case.
     message: "{{property}} should be kebab-case (lower-case and separated with hyphens)"
     severity: warn
     given: $.paths[*]~
@@ -62,7 +62,7 @@ Rulesets can extend other rulesets using the `extends` property, allowing you to
 extends: spectral:oas
 ```
 
-Extends can reference any [distributed ruleset](../guides/7-sharing-rulesets.md). It can be a single string, or an array of strings, and can contain either local file paths, URLs, or even NPM modules.
+Extends can reference any [distributed ruleset](../guides/7-sharing-rulesets.md). It can be a single string, or an array of strings, and can contain either local file paths, URLs, or even npm modules.
 
 ```yaml
 extends:
@@ -95,7 +95,7 @@ Formats are an optional way to specify which API description formats a rule, or
 - `json-schema-2019-09` (`$schema` says this is JSON Schema 2019-09)
 - `json-schema-2020-12` (`$schema` says this is JSON Schema 2020-12)
 
-Specifying the format is optional, so you can completely ignore this if all the rules you are writing apply to any document you lint, or if you have specific rulesets for different formats. If you'd like to use one ruleset for multiple formats, the formats key is here to help.
+Specifying the format is optional, so you can completely ignore this if all the rules you are writing apply to any document you lint, or if you have specific rulesets for different formats. If you'd like to use one ruleset for multiple formats, the `formats` key is here to help.
 
 ```yaml
 rules:

docs/getting-started/4-openapi.md

@@ -1,9 +1,7 @@
 # OpenAPI Support
 
-Spectral is a generic linter, but you can add an "oas" ruleset, with OAS being shorthand for the [OpenAPI Specification](https://openapis.org/specification).
+Spectral has a built-in [OpenAPI Specification](https://openapis.org/specification) ruleset that you can use to validate your OpenAPI files.
 
-Add `extends: "spectral:oas"` to your ruleset file to apply rules for OpenAPI v2 and v3.x, depending on the appropriate OpenAPI version used (detected through [formats](../getting-started/3-rulesets.md#formats). See the [OpenAPI Rules](../reference/openapi-rules.md).
+Add `extends: "spectral:oas"` ("oas" being shorthand for OpenAPI Specification) to your ruleset file to apply rules for OpenAPI v2 and v3.x, depending on the appropriate OpenAPI version being used (this is automatically detected through [formats](../getting-started/3-rulesets.md#formats)).
 
-<!-- theme: info -->
-
-> If you would like support for other API description formats like [RAML](https://raml.org/), message formats like [JSON:API](https://jsonapi.org/), etc., we recommend you start building custom but generic rulesets which can be shared with others. We've started putting together some over here on [OpenAPI Contrib](https://github.com/openapi-contrib/style-guides/).
+You can see a full list of the rules in this ruleset in [OpenAPI Rules](../reference/openapi-rules.md).

docs/getting-started/5-asyncapi.md

@@ -1,5 +1,7 @@
 # AsyncAPI Support
 
-Spectral is a generic linter, but you can add an [AsyncAPI v2](https://www.asyncapi.com/docs/specifications/v2.0.0) ruleset.
+Spectral has a built-in [AsyncAPI v2](https://www.asyncapi.com/docs/specifications/v2.0.0) ruleset that you can use to validate your AsyncAPI files.
 
-Add `extends: "spectral:asyncapi"` to your ruleset file to apply rules for AsyncAPI v2. See the [AsyncAPI Rules](../reference/asyncapi-rules.md).
+Add `extends: "spectral:asyncapi"` to your ruleset file to apply rules for AsyncAPI v2.
+
+You can see a full list of the rules in this ruleset in [AsyncAPI Rules](../reference/asyncapi-rules.md).

docs/guides/1-workflows.md

@@ -7,33 +7,35 @@ You can:
 1. Run [Spectral CLI](2-cli.md) against design docs and get early feedback.
 2. Run Spectral in [Stoplight Studio](https://stoplight.io/studio/?utm_source=github&utm_medium=spectral&utm_campaign=docs) or [VS Code](https://github.com/stoplightio/vscode-spectral?utm_source=github&utm_medium=spectral&utm_campaign=docs) as you work to avoid switching to CLI.
 3. Run Spectral as a [Git hook](#git-hooks) to enforce linting as part of the commit process.
-4. Use [Continuous Integration](#continuous-integration) to reject pull requests that don't match your rulesets and style-guide.
+4. Use [Continuous Integration](#continuous-integration) to reject pull requests that don't match your rulesets and style guide.
 
 ## Linting Design-First Workflows
 
-If you are using Studio, Spectral automatically runs as you work so you never need to switch to the CLI.
+If you are using [Stoplight Studio](https://stoplight.io/studio/?utm_source=github&utm_medium=spectral&utm_campaign=docs), Spectral automatically runs as you work so you never need to switch to the CLI.
 
 Seeing these errors and warnings facilitate consistent APIs, quickly and easily, without requiring "OpenAPI Gatekeepers" to manually enforce the rules.
 
 ## Linting Code-First Workflows
 
 Using Spectral gets a little tricky for developers who are following a code-first (a.k.a "design-second") workflow. If the API description documents live in YAML or JSON files, the design-first workflow can be used, with new changes being linted.
 
-If the API description documents live in some other format, such as comments or annotations inside code, consider using a tool with an export option on the CLI. Here's an example using [go-swagger](https://github.com/go-swagger/go-swagger).
+If the API description documents live in some other format, such as comments or annotations inside code, consider using a tool with an export option on the CLI. Here's an example using [go-swagger](https://github.com/go-swagger/go-swagger):
 
 ```bash
 swagger generate spec -o ./tmp/openapi.json && spectral lint ./tmp/openapi.json
 ```
 
-By the time you've written your code, if Spectral points anything out related to your actual API, and not providing feedback on the API description document itself, figuring out what to do next might be troublesome.
+After you've written your code and your API is already in production, if Spectral points anything out with your API description, figuring out what to do next might be troublesome.
 
-For example if the API has a bunch of URLs with underscores, then becoming consistent is either a case of waiting for the next major version and changing things in there, or taking a more evolution-based approach, aliasing `/example_url` to `/example-url`, then look into [deprecating the old URL](https://apisyouwonthate.com/blog/api-evolution-for-rest-http-apis/).
+For example, if the API has a bunch of URLs with underscores, then becoming consistent is either a case of waiting for the next major version and changing things in there, or taking a more evolution-based approach, aliasing `/example_url` to `/example-url`, then look into [deprecating the old URL](https://apisyouwonthate.com/blog/api-evolution-for-rest-http-apis/).
 
 ## Git-hooks
 
-Git commit hooks prevent developers form committing broken or low quality documents. Here's a simple solution using [Husky](https://github.com/typicode/husky).
+[Git hooks](https://git-scm.com/docs/githooks) are programs or commands you can set up and have them run when you commit or push. They can help lint your commit messages, run tests, or even lint your API descriptions with Spectral.
 
-```jsonc
+Here's an example of a Spectral Git hook using [Husky](https://github.com/typicode/husky):
+
+```json
 // package.json
 {
   "husky": {
@@ -50,8 +52,8 @@ See our [CLI documentation](./2-cli.md) to see what other arguments and options
 
 ## Continuous Integration
 
-Spectral can be used in any CI environment that runs run NodeJS or our Docker image: Jenkins, CircleCI, GitHub Actions, etc.
+Spectral can be used in any CI environment that runs Node.js or our Docker image: Jenkins, CircleCI, GitHub Actions, etc.
 
-By enabling the JUnit output format when you lint, most CI servers will show visual results helping people realise what mistakes were made and where.
+By enabling the JUnit output format when you lint, most CI servers will show visual results helping people realize which mistakes were made and where.
 
 Read our [Continuous Integration guide](8-continuous-integration.md) for more information on setting things up in your CI of choice.

docs/guides/2-cli.md

@@ -18,7 +18,7 @@ You can lint multiple files at the same time by passing on multiple arguments:
 spectral lint petstore.yaml https://example.com/petstore/openapi-v2.json https://example.com/todos/openapi-v3.json
 ```
 
-Alternatively you can use [glob syntax](https://github.com/mrmlnc/fast-glob#basic-syntax) to match multiple files at once:
+Alternatively, you can use [glob syntax](https://github.com/mrmlnc/fast-glob#basic-syntax) to match multiple files at once:
 
 ```bash
 spectral lint ./reference/**/*.oas*.{json,yml,yaml}
@@ -62,21 +62,21 @@ Here you can build a [custom ruleset](../getting-started/3-rulesets.md), or exte
 
 ## Error Results
 
-Spectral has a few different error severities: `error`, `warn`, `info` and `hint`, and they are in "order" from highest to lowest. By default, all results will be shown regardless of severity, but since v5.0, only the presence of errors will cause a failure status code of 1. Seeing results and getting a failure code for it are now two different things.
+Spectral has a few different error severities: `error`, `warn`, `info`, and `hint`, and they are in "order" from highest to lowest. By default, all results will be shown regardless of severity, but since v5.0, only the presence of errors will cause a failure status code of 1. Seeing results and getting a failure code for it are now two different things.
 
 The default behavior can be modified with the `--fail-severity=` option. Setting fail severity to `--fail-severity=info` would return a failure status code of 1 for any info results or higher. Using `--fail-severity=warn` will cause a failure status code for errors or warnings.
 
-Changing the fail severity will not affect output. To change what results Spectral CLI prints to the screen, add the `--display-only-failures` switch (or just `-D` for short). This will strip out any results which are below the specified fail severity.
+Changing the fail severity will not affect output. To change the results Spectral CLI prints to the screen, add the `--display-only-failures` switch (or just `-D` for short). This will strip out any results which are below the specified fail severity.
 
 ## Proxying
 
-To have requests made from Spectral be proxied through a server, you'd need to specify PROXY environment variable:
+To have requests made from Spectral be proxied through a server, you'd need to specify the `PROXY` environment variable:
 
 `PROXY=<<PROXY_SERVER_ADDRESS>> spectral lint spec.yaml`
 
 ## Custom \$ref Resolving
 
-If you want to customize \$ref resolving, you can leverage `--resolver` flag and pass a path to the JS file exporting a custom instance of json-ref-resolver Resolver.
+If you want to customize \$ref resolving, you can leverage the `--resolver` flag and pass a path to the JS file exporting a custom instance of json-ref-resolver Resolver.
 
 ### Example
 
@@ -87,7 +87,7 @@ const { Resolver } = require("@stoplight/json-ref-resolver");
 
 module.exports = new Resolver({
   resolvers: {
-    // pass any resolver for protocol you need
+    // pass any resolver for the protocol you need
   },
 });
 ```