From b2dbf2573345237125d6299913e09175fcc1be7b Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Thu, 25 Aug 2022 11:26:31 -0500 Subject: [PATCH 01/13] docs(repo): replace NPM with npm --- docs/getting-started/1-concepts.md | 4 ++-- docs/getting-started/2-installation.md | 2 +- docs/getting-started/3-rulesets.md | 2 +- docs/guides/7-sharing-rulesets.md | 8 ++++---- docs/guides/8-continuous-integration.md | 2 +- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/getting-started/1-concepts.md b/docs/getting-started/1-concepts.md index e643c7cdf..009e3f996 100644 --- a/docs/getting-started/1-concepts.md +++ b/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. diff --git a/docs/getting-started/2-installation.md b/docs/getting-started/2-installation.md index 75b496bc9..f06d1f66e 100644 --- a/docs/getting-started/2-installation.md +++ b/docs/getting-started/2-installation.md @@ -14,7 +14,7 @@ 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 diff --git a/docs/getting-started/3-rulesets.md b/docs/getting-started/3-rulesets.md index 5da44065c..a4e9a5cce 100644 --- a/docs/getting-started/3-rulesets.md +++ b/docs/getting-started/3-rulesets.md @@ -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: diff --git a/docs/guides/7-sharing-rulesets.md b/docs/guides/7-sharing-rulesets.md index 0d4214d90..5d255b53b 100644 --- a/docs/guides/7-sharing-rulesets.md +++ b/docs/guides/7-sharing-rulesets.md @@ -5,7 +5,7 @@ A [ruleset](../getting-started/3-rulesets.md) becomes infinitely more useful whe To help you out distribute your rulesets among the others, Spectral provides a few ways to load rulesets from a variety of resources: - via a HTTP server -- via [NPM](#npm) +- via [npm](#npm) - via the filesystem Or mix and match! @@ -44,9 +44,9 @@ As with any ruleset, you can pass these directly to the [Spectral CLI](./2-cli.m spectral lint -r https://example.com/some-ruleset.yml ``` -## NPM +## npm -As Spectral is a [NPM](https://www.npmjs.com/) package, we support loading rulesets from other NPM packages. +As Spectral is an [npm](https://www.npmjs.com/) package, we support loading rulesets from other npm packages. Not only it lets you serve files without a need for hosting your own server or uploading it somewhere else, but also supports versioning out of the box, and makes it easy to bundle a ruleset with custom rulesets. @@ -126,7 +126,7 @@ Pegging a ruleset on given version is possible through a `package.json`: } ``` -If you Spectral in a browser or don't want to install the package, you can also reference that package through the use of CDNs for NPM repository, such as [unpkg.com](https://unpkg.com/): +If you use Spectral in a browser or don't want to install the package, you can also reference that package through the use of CDNs for npm repositories, such as [unpkg.com](https://unpkg.com/): ```yaml extends: diff --git a/docs/guides/8-continuous-integration.md b/docs/guides/8-continuous-integration.md index f432d25f6..4b97d96a5 100644 --- a/docs/guides/8-continuous-integration.md +++ b/docs/guides/8-continuous-integration.md @@ -1,6 +1,6 @@ # Continuous Integration -Spectral CLI can be run anywhere that NPM packages can be installed and run via CLI, which these days is pretty much any CI solution going. +Spectral CLI can be run anywhere that npm packages can be installed and run via CLI, which these days is pretty much any CI solution going. Here are some examples of Spectral in various CI solutions to give you an idea. From e05fea1935ca9e4004e8007a3f4ec063e944f710 Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Thu, 25 Aug 2022 11:30:03 -0500 Subject: [PATCH 02/13] docs(repo): replace NodeJS with Node.js --- docs/guides/1-workflows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/1-workflows.md b/docs/guides/1-workflows.md index dfb4f978d..3a1922527 100644 --- a/docs/guides/1-workflows.md +++ b/docs/guides/1-workflows.md @@ -50,7 +50,7 @@ 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. From 4952da0013beff1cc4ba95e96c49f83011cf1698 Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Thu, 25 Aug 2022 12:24:19 -0500 Subject: [PATCH 03/13] docs(repo): grammarly pass for getting-started --- docs/getting-started/2-installation.md | 13 +++++++------ docs/getting-started/3-rulesets.md | 4 ++-- docs/getting-started/4-openapi.md | 8 +++----- docs/getting-started/5-asyncapi.md | 6 ++++-- 4 files changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/getting-started/2-installation.md b/docs/getting-started/2-installation.md index f06d1f66e..bee2c9e02 100644 --- a/docs/getting-started/2-installation.md +++ b/docs/getting-started/2-installation.md @@ -1,12 +1,12 @@ # 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 @@ -20,19 +20,20 @@ For users without Node.js and/or npm/Yarn, we provide standalone packages for [a 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 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. -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: diff --git a/docs/getting-started/3-rulesets.md b/docs/getting-started/3-rulesets.md index a4e9a5cce..6e229c328 100644 --- a/docs/getting-started/3-rulesets.md +++ b/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[*]~ @@ -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: diff --git a/docs/getting-started/4-openapi.md b/docs/getting-started/4-openapi.md index 579e7ab86..36919ec23 100644 --- a/docs/getting-started/4-openapi.md +++ b/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)). - - -> 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). diff --git a/docs/getting-started/5-asyncapi.md b/docs/getting-started/5-asyncapi.md index 3ff51ec95..7ab32585b 100644 --- a/docs/getting-started/5-asyncapi.md +++ b/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). From 69a94a8f933b8c863fb00c1b5cceb9ae309fdcff Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Fri, 26 Aug 2022 11:25:58 -0500 Subject: [PATCH 04/13] docs(repo): grammarly review for workflows guide --- docs/guides/1-workflows.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/guides/1-workflows.md b/docs/guides/1-workflows.md index 3a1922527..b6ccdee4f 100644 --- a/docs/guides/1-workflows.md +++ b/docs/guides/1-workflows.md @@ -7,11 +7,11 @@ 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. @@ -19,19 +19,21 @@ Seeing these errors and warnings facilitate consistent APIs, quickly and easily, 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. + +Here's an example of a Spectral Git hook using [Husky](https://github.com/typicode/husky): ```jsonc // package.json @@ -52,6 +54,6 @@ See our [CLI documentation](./2-cli.md) to see what other arguments and options 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 what 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. From db00680522ed5bf82b29b04f07d5d8e311b5fc63 Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Wed, 31 Aug 2022 18:01:38 -0500 Subject: [PATCH 05/13] docs(repo): grammarly pass for workflow and cli guides --- docs/guides/1-workflows.md | 2 +- docs/guides/2-cli.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/guides/1-workflows.md b/docs/guides/1-workflows.md index b6ccdee4f..55ba82097 100644 --- a/docs/guides/1-workflows.md +++ b/docs/guides/1-workflows.md @@ -35,7 +35,7 @@ For example, if the API has a bunch of URLs with underscores, then becoming cons Here's an example of a Spectral Git hook using [Husky](https://github.com/typicode/husky): -```jsonc +```json // package.json { "husky": { diff --git a/docs/guides/2-cli.md b/docs/guides/2-cli.md index 154acbf8c..846b7aa93 100644 --- a/docs/guides/2-cli.md +++ b/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=<> 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 }, }); ``` From 24f0dbad9358bb0878b7959a37c899a02ed07b19 Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Wed, 31 Aug 2022 18:21:15 -0500 Subject: [PATCH 06/13] docs(repo): grammarly pass for custom rulesets --- docs/guides/4-custom-rulesets.md | 49 ++++++++++++++------------------ 1 file changed, 22 insertions(+), 27 deletions(-) diff --git a/docs/guides/4-custom-rulesets.md b/docs/guides/4-custom-rulesets.md index 9d1a1e5c2..99d3fd902 100644 --- a/docs/guides/4-custom-rulesets.md +++ b/docs/guides/4-custom-rulesets.md @@ -1,8 +1,8 @@ # Custom Rulesets -Customising existing rulesets might be all you need at first, but at some point you will want to make a custom ruleset. For example, the OpenAPI and AsyncAPI rulesets help create better quality descriptions of APIs, but you could create a custom ruleset to tell you how to make better APIs. This approach is how huge companies automate [API Style Guides](https://stoplight.io/api-style-guides-guidelines-and-best-practices/?utm_source=github&utm_medium=spectral&utm_campaign=docs), instead of writing up giant Wiki documents that nobody reads. +Customizing existing rulesets might be all you need at first, but at some point, you will want to make a custom ruleset. For example, the OpenAPI and AsyncAPI rulesets help create better quality descriptions of APIs, but you could create a custom ruleset to tell you how to make better APIs. This approach is how huge companies automate [API Style Guides](https://stoplight.io/api-style-guides-guidelines-and-best-practices/?utm_source=github&utm_medium=spectral&utm_campaign=docs), instead of writing up giant Wiki documents that nobody reads. -If you'd like to make sure your APIs are consistent and high quality before they've even built, create a ruleset with rules that define how URLs should work, what security schemes are appropriate, or what error formats should be used. Read our article _[Six Things You Should Include in Your API Style Guide](https://blog.stoplight.io/six-things-you-should-include-in-your-api-style-guide?utm_source=github&utm_medium=spectral&utm_campaign=docs)._ +If you'd like to make sure your APIs are consistent and high quality even before they're built, create a ruleset with rules that define how URLs should work, what security schemes are appropriate, or what error formats should be used. Read our article _[Six Things You Should Include in Your API Style Guide](https://blog.stoplight.io/six-things-you-should-include-in-your-api-style-guide?utm_source=github&utm_medium=spectral&utm_campaign=docs)._ Or you can create a custom ruleset to make sure your Jekyll or Gatsby custom data is valid. Whatever you want to do, to start with you'll need to create some rules. @@ -52,9 +52,7 @@ For example, if you want to enforce conventions on the folder structure used for [splitting up documents](https://blog.stoplight.io/keeping-openapi-dry-and-portable?utm_medium=spectral&utm_source=github&utm_campaign=docs). -If your rule needs to access the raw `$ref` reference values, you can set -`resolved: false` to allow the rule to receive the raw un-resolved version of -the document. Otherwise `resolved: true` is the default. +If your rule needs to access the raw `$ref` reference values, you can set `resolved: false` to allow the rule to receive the raw un-resolved version of the document. Otherwise `resolved: true` is the default. Here's an example of a rule that can access `$ref` values: @@ -94,7 +92,7 @@ then: 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` JSONPath. The value can also be `@key` to apply the rule to a keys of an object. +The `field` keyword is optional and is used to apply the function to a specific property in an object. If omitted the function will be applied to the entire target of the `given` JSONPath. The value can also be `@key` to apply the rule to the keys of an object. ```yaml given: "$.responses" @@ -174,7 +172,7 @@ rules: This provides a new description, but anything can be changed. -If you're just looking change the severity of the rule, there is a handy shortcut. +If you're just looking to change the severity of the rule, there is a handy shortcut. ### Changing Rule Severity @@ -190,7 +188,7 @@ Available severity levels are `error`, `warn`, `info`, `hint`, and `off`. ## Recommended or All -Rules by default are considered "recommended" (equivalent to a rule having) `recommended: true` but they can also be marked as not recommended with `recommended: false`. This can help scenarios like rolling out rulesets across API landscapes with a lot of legacy APIs which might have a hard time following every rule immediately. A two-tier system for rules can be helpful here, to avoid requiring several rulesets for this basic use-case. +Rules by default are considered "recommended" (equivalent to a rule having) `recommended: true` but they can also be marked as not recommended with `recommended: false`. This can help scenarios like rolling out rulesets across API landscapes with a lot of legacy APIs which might have a hard time following every rule immediately. A two-tier system for rules can be helpful here, to avoid requiring several rulesets for this basic use case. You can try this out with the core OpenAPI ruleset. If you simply extend the ruleset, by default you will only get the recommended rules. @@ -198,7 +196,7 @@ You can try this out with the core OpenAPI ruleset. If you simply extend the rul extends: [[spectral:oas, recommended]] ``` -Far more rule exist than just the recommended ones, there are various other rules which will help you create high quality OpenAPI descriptions. +Far more rules exist than just the recommended ones, there are various other rules which will help you create high-quality OpenAPI descriptions. ```yaml extends: [[spectral:oas, all]] @@ -216,7 +214,7 @@ rules: operation-operationId-unique: off ``` -The example above will run all of the rules defined in the `spectral:oas` ruleset (rather than the default behavior that runs only the recommended ones), with one exceptions - we turned `operation-operationId-unique` off. +The example above will run all of the rules defined in the `spectral:oas` ruleset (rather than the default behavior that runs only the recommended ones), with one exception - we turned `operation-operationId-unique` off. ### Enabling Rules @@ -228,11 +226,11 @@ rules: 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:oas` ruleset. +The example above will only run the rule `operation-operationId-unique` that we enabled since we passed `off` to disable all rules by default when extending the `spectral:oas` ruleset. ## Parsing Options -If you do not care about duplicate keys or invalid values (such as non-string mapping keys in YAML), you can tune their severity using `parserOptions` setting. +If you do not care about duplicate keys or invalid values (such as non-string mapping keys in YAML), you can tune their severity using the `parserOptions` setting. ```yaml extends: spectral:oas @@ -247,7 +245,7 @@ parserOptions: Optionally provide a documentation URL to your ruleset in order to help end-users find more information about various warnings. Result messages will sometimes be more than enough to explain what the problem is, but it can also be beneficial to explain _why_ a message exists, and this is a great place to do that. -Whatever you link you provide, the rule name will be appended as an anchor. +Whatever link you provide, the rule name will be appended as an anchor. ```yaml # 👇 This line allows people to find more information @@ -339,7 +337,7 @@ This code example adds two rules: `valid-rule` and `only-new-json-schema`, thing For those of you using custom functions, the keywords `functions` & `functionOptions` have been removed, as they were designed to help Spectral find your functions. Now functions are passed as a variable, instead of using a string that contains the name like the JSON/YAML formats. -For now the JSON, YAML, and JS, are all being maintained, and there are no current plans to drop support for any of them. +For now the JSON, YAML, and JS formats are all being maintained, and there are no current plans to drop support for any of them. ## Aliases @@ -365,7 +363,7 @@ aliases: - "$.paths[*]~" ``` -If you deal with a variety of different spec, you may find the above approach insufficient, particularly when the shape of the document is notably different. +If you deal with a variety of different specs, you may find the above approach insufficient, particularly when the shape of the document is notably different. In such a case, you may want to consider using scoped aliases. ```yaml @@ -383,12 +381,10 @@ aliases: - $.components.parameters[*] ``` -Now, if you referenced `SharedParameterObject` alias, the chosen path would be determined based on the document you use. +Now, if you referenced the `SharedParameterObject` alias, the chosen path would be determined based on the document you use. For instance, if a given document matched OpenAPI 2.x, `$.parameters[*]` would be used as the JSONPath expression. -Having a closer look on the example above, one may notice that it'd be still somewhat complicated to target _all_ Parameter Objects -that a specific OpenAPI document may contain. -To make it more feasible and avoid overly complex JSONPath expressions, `given` can be an array. +Having a closer look at the example above, one may notice that it'd be still somewhat complicated to target _all_ Parameter Objects that a specific OpenAPI document may contain. To make it more feasible and avoid overly complex JSONPath expressions, `given` can be an array. ```yaml aliases: @@ -415,8 +411,7 @@ aliases: Rulesets can then reference aliases in the [given](#given) keyword, either in full: `"given": "#Paths"`, or use it as a prefix for further JSONPath syntax, like dot notation: `"given": "#ParameterObject.name"`. -Bear in mind that an alias has to be explicitly defined in either at the top-level or inside an override. -This is to avoid ambiguity. +Keep in mind that an alias has to be explicitly defined either at the root level or inside an override. This is to avoid ambiguity. ```yaml aliases: @@ -451,7 +446,7 @@ overrides: - legacy/**/*.json rules: falsy-value: - given: "#Value" # invalid because undeclared both at the top-level and the override. Note that this could be technically resolvable for some JSON documents, because the previous override block has the alias, but to spare some headaches, we demand an alias to be explicitly defined. + given: "#Value" # invalid because undeclared both at the top-level and the override. Note that this could be technically resolvable for some JSON documents because the previous override block has the alias, but to spare some headaches, we demand an alias to be explicitly defined. severity: error then: function: falsy @@ -461,7 +456,7 @@ overrides: ## Overrides -Previously Spectral supported exceptions, which were limited in their ability to target particular rules on specific files or parts of files, or changing parts of a rule. Overrides is the much more powerful version of exceptions, with the ability to customize ruleset usage for different files and projects without having to duplicate any rules. +Previously Spectral supported exceptions, which were limited in their ability to target particular rules on specific files or parts of files, or change parts of a rule. Overrides is the much more powerful version of exceptions, with the ability to customize ruleset usage for different files and projects without having to duplicate any rules. Overrides can be used to apply rulesets on: @@ -522,7 +517,7 @@ Please bear in mind that overrides are only applied to the _root_ documents. If **Example:** -Given the following 2 YAML documents +Given the following 2 YAML documents: ```yaml # my-document.yaml @@ -545,7 +540,7 @@ required: - id ``` -and the ruleset below +And the ruleset below: ```json { @@ -569,7 +564,7 @@ and the ruleset below } ``` -running `spectral lint my-document.yaml` will result in +Running `spectral lint my-document.yaml` will result in the following output: ``` /project/User.yaml @@ -578,7 +573,7 @@ running `spectral lint my-document.yaml` will result in ✖ 1 problem (0 errors, 1 warning, 0 infos, 0 hints) ``` -while executing `spectral lint User.yaml` will output +While executing `spectral lint User.yaml` will output: ``` No results with a severity of 'error' or higher found! From 4b4f8bf3286f2898a679ee2b18d79fd221b385e5 Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Wed, 31 Aug 2022 19:11:18 -0500 Subject: [PATCH 07/13] docs(repo): grammarly pass for custom functions --- docs/guides/5-custom-functions.md | 91 ++++++++++++++++--------------- 1 file changed, 47 insertions(+), 44 deletions(-) diff --git a/docs/guides/5-custom-functions.md b/docs/guides/5-custom-functions.md index 2d5bce5c9..6abd035f7 100644 --- a/docs/guides/5-custom-functions.md +++ b/docs/guides/5-custom-functions.md @@ -1,8 +1,8 @@ # Custom Functions -If the core functions are not enough for your [custom ruleset](../getting-started/3-rulesets.md), Spectral allows you to write and use your own custom functions. +If the core functions are not enough for your [custom ruleset](../getting-started/3-rulesets.md), Spectral allows you to write and use custom functions. -Create a directory to contain your new functions. By default `functions/` is assumed. +Start by creating a directory to contain your new functions. By default, Spectral looks for the `functions/` folder. **functions/abc.js** @@ -32,7 +32,7 @@ rules: function: "abc" ``` -The function is looking for a targetVal of `"hello"` for anywhere its applied, and this rule uses a given target of `$.greeting`. +The function is looking for a `targetVal` of `"hello"` for anywhere it's applied, and this rule uses a given target of `$.greeting`. If the object being linted looks like this, everything is going to be ok. @@ -111,11 +111,11 @@ export default createRulesetFunction({ ### input -`input` the value the custom function is provided with and is supposed to lint against. +`input` is the value the custom function is provided with and is supposed to lint against. It's based on `given` [JSON Path][jsonpath] expression defined on the rule and optionally `field` if placed on `then`. -For example, a rule might have `given` with a JSON Path expression of `$`, and the following partial of an OpenAPI document: +For example, a rule might have `given` with a JSON Path expression of `$`, and the following partial OpenAPI document: ```yaml openapi: 3.0.0 @@ -127,47 +127,45 @@ In this example, `targetValue` would be a JavaScript object literal containing ` ### options -Options corresponds to `functionOptions` that's defined in `then` property of each rule. +`options` corresponds to `functionOptions` that's defined in the `then` property of each rule. -Each rule can specify options that each function should receive. This can be done as follows +Each rule can specify options that each function should receive. This can be done as follows: ```yaml operation-id-kebab-case: given: "$..operationId" then: function: pattern - functionOptions: # this object be passed down as options to the custom function + functionOptions: # this object is passed down as options to the custom function match: ^[a-z][a-z0-9\-]*$ ``` ### context -`context.path` contains a resolved property path pointing to the place in the document +`context.path` contains a resolved property path pointing to a place in the document. -`context.document` provides an access to the document that we attempt to lint. -You may find it useful if you'd like to see which formats were applied to it, or in case you'd like to get its unresolved version. +`context.document` provides access to the document that we attempt to lint. You may find it useful if you'd like to see which formats were applied to it, or in case you'd like to get its unresolved version. -`context.documentInventory` provides an access to resolved and unresolved documents as well, $ref resolution graph, as some other advanced properties. -You shouldn't need it for most of the time. +`context.documentInventory` provides access to resolved and unresolved documents, the $ref resolution graph, as well as some other advanced properties. You shouldn't need it most of the time. -`context.rule` an actual rule your function was called for. +`context.rule` is an actual rule your function was called for. -Custom functions take exactly the same arguments as core functions do, so you are more than welcome to take a look at the existing implementation. +Custom functions take the same arguments as core functions do, so you are more than welcome to take a look at the existing implementation. The process of creating a function involves 2 steps: -- create a js file inside of a directory called `functions` that should be placed next to your ruleset file -- create a `functions` array in your ruleset if you haven't done it yet and place a string with the filename without `.js` extension +- Create a `.js` file inside of a directory called `functions` that should be placed next to your ruleset file +- Create a `functions` array in your ruleset and place a string using the function filename without the `.js` extension -## Returning multiple results +## Returning Multiple Results -Many functions will return a single message, but it is possible for a function to return multiple. +Many functions will return a single message, but a function can return multiple messages. For example, if a rule is created to make sure something is unique, it could either: -- return a single error for the entire array which lists offending values in a comma separated list -- return a single error for the array value which contains the first offending non-unique item -- return multiple errors for each duplicate value located +- Return a single error for the entire array which lists offending values in a comma-separated list +- Return a single error for the array value which contains the first offending non-unique item +- Return multiple errors for each duplicate value located How exactly you chose to implement messages depends on the rule at hand and probably personal preference too. @@ -235,14 +233,15 @@ export default createRulesetFunction( ); ``` -It's worth keeping in mind, Spectral will attempt to deduplicate messages when they bear the same `code` and target the same `path`. +It's worth keeping in mind, Spectral will attempt to deduplicate messages when they have the same `code` and target the same `path`. -As such, when your custom function is susceptible to return more than one result, you have to specify a different `path` for each result. +As such, if your custom function might return more than one result, you should specify a different `path` for each result. -## Referencing core functions +## Referencing Core Functions Your custom function may also build on top of existing functions Spectral offers. -Make sure to provide all arguments that was originally passed to your function, otherwise a core function may misbehave. + +Make sure to provide all arguments that were originally passed to your function, otherwise, a core function may misbehave. ### Example @@ -251,7 +250,7 @@ import { truthy } from "@stoplight/spectral-functions"; export default function (input, ...args) { if (input.info["skip-info"] === true) { - // if info has a property with key called "skip-info" and its value is true, let's do nothing + // if info has a property with a key called "skip-info" and its value is true, let's do nothing return; } @@ -266,8 +265,8 @@ As of Spectral 5.4.0, custom functions can also be asynchronous. -> Ideally linting should always be deterministic, which means if its run 10 times it should return the same results 10 times. To ensure this is the case, please refrain from introducing any logic that is prone to non-deterministic behavior. Examples of this might be contacting external service you have no control over, or that might be unstable, or change the way it responds over time. -> While, it may seem tempting to have a function that does so, the primary use case is to support libraries that makes async fs calls or exchanging information, i.e. obtaining a dictionary file, with a locally running server, etc. +> Ideally linting should always be deterministic, which means if it's run 10 times it should return the same results 10 times. To ensure this is the case, please refrain from introducing any logic that is prone to non-deterministic behavior. Examples of this might be contacting an external service you have no control over, or that is unstable, or that changes the way it responds over time. +> While, it may seem tempting to have a function that does so, the primary use case is to support libraries that makes async fs calls or exchange information, i.e. obtaining a dictionary file, with a locally running server, etc. **functions/dictionary.js** @@ -309,7 +308,7 @@ rules: ## Changing Directory -Want to place your functions in somewhere other than the `functions/` directory? Use the `functionsDir` keyword in your ruleset. +Want to place your functions somewhere other than the `functions/` directory? Use the `functionsDir` keyword in your ruleset. ```yaml functions: @@ -332,28 +331,32 @@ This indicates that almost any arbitrary code can be executed. Potential risks include: -- data / credentials infiltration, -- data tampering, -- running cpu-intensive tasks, i.e. crypto-mining. +- Data/credentials infiltration +- Data tampering +- Running cpu-intensive tasks, i.e. crypto-mining While the risk is relatively low, you should be careful about including **external rulesets** you are not in charge of, in particular those that leverage custom functions. + You are strongly encouraged to review the custom functions a given ruleset provides. What you should hunt for is: -- obfuscated code, -- calls to an untrusted external library, -- places where remote code is executed. +- Obfuscated code +- Calls to an untrusted external library +- Places where remote code is executed -If you notice any weirdness, consider forking the ruleset and removal of any evil-looking code. +If you notice any weirdness, consider forking the ruleset and removing any evil-looking code. ## Inheritance -Core functions can be overridden with custom rulesets, so if you'd like to make your own truthy go ahead. Custom functions are only available in the ruleset which defines them, so loading a foo in one ruleset will not clobber a foo in another ruleset. +Core functions can be overridden with custom rulesets, so if you'd like to make your own `truthy` function you can do so. + +Custom functions are only available in the ruleset which defines them, so loading a `foo` function in one ruleset will not affect a `foo` function in another ruleset. + +## Performance Tips -## Performance tips +Try to avoid allocating objects as much as possible if your custom function is very generic, and therefore is expected to be used by plenty of rules. -- try to avoid allocating objects as much as possible if your custom function might is very generic, and therefore is expected to be used by plenty of rules. - If your document is huge enough, and JSON path expression is loose (meaning it matches a lot of properties), your function might be called hundreds of thousands of times. +If your document is big, and the JSON path expression is loose (meaning it matches a lot of properties), your function might be called hundreds of thousands of times. ```js // bad @@ -381,14 +384,14 @@ export default (targetVal, { excludedWords }) => { Spectral is meant to support a variety of environments, so ideally your function should behave similarly in Node.js and browser contexts. Do not rely on globals or functions specific to a particular environment. For example, do not expect the browser `window` global to always be available, since this global is not available in Node.js environments. -If you need to access environment specific APIs, make sure you provide an alternative for other environments. A good example of such a situation is `fetch` - a function available natively in a browser context, but missing in Node.js. +If you need to access environment-specific APIs, make sure you provide an alternative for other environments. A good example of such a situation is `fetch` - a function available natively in a browser context, but missing in Node.js. -To keep your code cross-platform, you'd need to use a cross platform package such as [node-fetch](https://www.npmjs.com/package/node-fetch) or [isomorphic-fetch](https://www.npmjs.com/package/isomorphic-fetch), both of which implement spec-compliant fetch API and work in Node.js. +To keep your code cross-platform, you'd need to use a cross-platform package such as [node-fetch](https://www.npmjs.com/package/node-fetch) or [isomorphic-fetch](https://www.npmjs.com/package/isomorphic-fetch), both of which implement spec-compliant fetch API and work in Node.js. ## Code Transpilation We encourage you to not transpile the code to ES5 if you can help it. Spectral does not support older environments than ES2019, so there is no need to bloat the bundle with useless transformations and polyfills. Ship untransformed async/await, do not include unneeded shims, it's all good. -Prior to 6.x, Spectral hadn't supported ES Modules, yet as of recently using ES Modules is the recommended way to do things. +Before 6.x, Spectral hadn't supported ES Modules, yet as of recently using ES Modules is the recommended way to do things. [jsonpath]: https://jsonpath.com/ From 56d1ae2ca949990b3611e2e22ee24b4415e80651 Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Thu, 1 Sep 2022 16:52:34 -0500 Subject: [PATCH 08/13] docs(repo): grammarly pass for 7 and 8 guides --- docs/guides/7-sharing-rulesets.md | 8 ++++---- docs/guides/8-continuous-integration.md | 8 +++++--- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/guides/7-sharing-rulesets.md b/docs/guides/7-sharing-rulesets.md index 5d255b53b..a6b3478c7 100644 --- a/docs/guides/7-sharing-rulesets.md +++ b/docs/guides/7-sharing-rulesets.md @@ -4,7 +4,7 @@ A [ruleset](../getting-started/3-rulesets.md) becomes infinitely more useful whe To help you out distribute your rulesets among the others, Spectral provides a few ways to load rulesets from a variety of resources: -- via a HTTP server +- via an HTTP server - via [npm](#npm) - via the filesystem @@ -21,7 +21,7 @@ There are various pros and cons to each approach, so see what is right for you. ## HTTP Server -At its most basic level, a Spectral ruleset is just a JSON or YAML file. It can be hosted anywhere you like: on your web hosting, Amazon S3, or anywhere text files are accessible, and then pulled into your own local ruleset in the filesystem: +At its most basic level, a Spectral ruleset is just a JSON or YAML file. It can be hosted anywhere you like: on your web hosting, Amazon S3, or anywhere text files are accessible, and then pulled into your local ruleset in the filesystem: **ruleset.yaml** @@ -48,7 +48,7 @@ spectral lint -r https://example.com/some-ruleset.yml As Spectral is an [npm](https://www.npmjs.com/) package, we support loading rulesets from other npm packages. -Not only it lets you serve files without a need for hosting your own server or uploading it somewhere else, but also supports versioning out of the box, and makes it easy to bundle a ruleset with custom rulesets. +Not only does it let you serve files without a need for hosting your own server or uploading it somewhere else, but also supports versioning out of the box, and makes it easy to bundle a ruleset with custom rulesets. This is a very basic example showing how the directory structure as well as package.json may look like. @@ -116,7 +116,7 @@ extends: - example-spectral-ruleset ``` -Pegging a ruleset on given version is possible through a `package.json`: +Locking a ruleset on a given version is possible through `package.json`: ```json { diff --git a/docs/guides/8-continuous-integration.md b/docs/guides/8-continuous-integration.md index 4b97d96a5..4f4d4e9f5 100644 --- a/docs/guides/8-continuous-integration.md +++ b/docs/guides/8-continuous-integration.md @@ -37,7 +37,9 @@ workflows: - lint ``` -Change the `openapi.yaml` to point to whatever documents you want to lint, and use -f (format) to pick the JUnit output format. This is a standard test format that many CI servers understand, and means you should be able to see the errors in the Test interface. +Make sure to change `openapi.yaml` to point to whatever documents you want to lint. + +The `-f` (format) flag is used in the script to pick the JUnit output format. This is a standard test format that many CI servers understand, and means you should be able to see the errors in the Test interface. ![On the CircleCI build results page there is a tab called Tests, which will show Spectral results so long as the junit format has been enabled](../img/ci-circleci.png) @@ -69,9 +71,9 @@ lint:spectral: junit: $CI_PROJECT_DIR/spectral-report.xml ``` -Note that this CI job exposes Spectral results on the merge request page, along with any other test output you may have. To ensure that GitLab can parse the output of spectral, we use the `-f junit`flag. +Make sure to change `openapi.yaml` to point to whatever documents you want to lint. -You will also need to edit your `openapi.yaml` file to point to the particular documents you want to lint. +The `-f` (format) flag is used in the script to pick the JUnit output format. This is a standard test format that many CI servers understand, and means you should be able to see the Spectral output on the merge request page. ## Jenkins From 2af54fafb1d7164317686e8faa51072baea69dc7 Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Thu, 1 Sep 2022 16:59:56 -0500 Subject: [PATCH 09/13] docs(repo): grammarly pass for migration guides --- docs/migration-guides/5.0.md | 9 +++++---- docs/migration-guides/6.0.md | 19 +++++-------------- 2 files changed, 10 insertions(+), 18 deletions(-) diff --git a/docs/migration-guides/5.0.md b/docs/migration-guides/5.0.md index 16c984f6f..581efb38e 100644 --- a/docs/migration-guides/5.0.md +++ b/docs/migration-guides/5.0.md @@ -5,9 +5,9 @@ this migration guide covers the most notable changes. ### I have my own custom rulesets... -1. oas2 and oas3 rulesets have been merged to oas +1. `oas2` and `oas3` rulesets have been merged to `oas` -From now on, you don't need to worry about oas2 or oas3, you simply extend oas ruleset and Spectral will figure out which rules to apply based on given formats. +From now on, you don't need to worry about `oas2` or `oas3`, you simply extend the `oas` ruleset and Spectral will figure out which rules to apply based on given formats. **Spectral v4**: @@ -27,8 +27,9 @@ From now on, you don't need to worry about oas2 or oas3, you simply extend oas r 2. All rules are recommended by default now -Previously it wasn't quite clear that you need to make rule recommended in order to have it enabled by default. -We addressed it and right now you need to explicitly mark rule as unrecommended assuming you do want it to be so. +Previously it wasn't quite clear that you need to make a rule recommended to have it enabled by default. + +We addressed it and right now you need to explicitly mark a rule as unrecommended assuming you do want it to be so. **Spectral v4**: diff --git a/docs/migration-guides/6.0.md b/docs/migration-guides/6.0.md index 12f968f87..b6d8856f2 100644 --- a/docs/migration-guides/6.0.md +++ b/docs/migration-guides/6.0.md @@ -2,14 +2,8 @@ ## General -1. Spectral has become a monorepo now and CLI <-> Core have been split into separate packages. - If you intend to use a CLI version of Spectral make sure to install `@stoplight/spectral-cli`. - Otherwise, go with `@stoplight/spectral-core` which is the JS API. - -2. No default ruleset is loaded by default as of now, thus if you don't supply a ruleset, Spectral will refuse to lint the document. - If you use CLI, make sure to have a valid ruleset in your project or use a `--ruleset` flag. - JS API has a method called `setRuleset` which can be used to set the relevant ruleset. - +1. Spectral has become a monorepo now and CLI <-> Core have been split into separate packages. If you intend to use a CLI version of Spectral make sure to install `@stoplight/spectral-cli`. Otherwise, go with `@stoplight/spectral-core` which is the JS API. +2. No default ruleset is loaded by default as of now, thus if you don't supply a ruleset, Spectral will refuse to lint the document. If you use CLI, make sure to have a valid ruleset in your project or use a `--ruleset` flag. JS API has a method called `setRuleset` which can be used to set the relevant ruleset. 3. Spectral is stricter overall and certain soft errors that previously were marked as warnings will throw now. ## Core @@ -70,16 +64,13 @@ const spectral = new Spectral({ ## Functions -1. `schema` function uses Ajv v8 in favor of Ajv v6. It is preferred to provide JSON Schema Draft 7 schemas or newer, albeit older drafts are also supported via json-schema-migrate. - `oasVersion` is no longer supported. Use `oasSchema` function from the OAS ruleset if you want to supply OAS Schema Object. - +1. `schema` function uses Ajv v8 in favor of Ajv v6. It is preferred to provide JSON Schema Draft 7 schemas or newer, albeit older drafts are also supported via json-schema-migrate. `oasVersion` is no longer supported. Use the `oasSchema` function from the OAS ruleset if you want to supply an OAS Schema Object. 2. `schemaPath` is no longer available. If you happened to use this function, you can write a custom function that implements the same functionality. ## CLI 1. deprecated `--show-unmatched-globs` flag has been removed. Alternative available: `--fail-on-unmatched-globs` - -2. `--skip-rule` has been removed. Use a custom ruleset instead - set a severity of a particular rule to "off". +2. `--skip-rule` has been removed. Use a custom ruleset instead - set the severity of a particular rule to "off". ## Rulesets @@ -115,7 +106,7 @@ Change: all reusable `components` are now validated. - `operation-default-response` -Workaround: Insert the following rule to your custom ruleset. +Workaround: Insert the following rule in your custom ruleset. ```json "operation-default-response": { From fa82e5d6633effe5583b149aa7f8cc09606d945c Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Thu, 1 Sep 2022 17:09:01 -0500 Subject: [PATCH 10/13] docs(repo): grammarly pass for asyncapi-rules --- docs/reference/asyncapi-rules.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/reference/asyncapi-rules.md b/docs/reference/asyncapi-rules.md index 26a4a33f2..9e547a7f7 100644 --- a/docs/reference/asyncapi-rules.md +++ b/docs/reference/asyncapi-rules.md @@ -40,7 +40,7 @@ Channel servers must be defined in the `servers` object. asyncapi: "2.0.0" info: title: Awesome API - description: A very well defined API + description: A very well-defined API version: "1.0" servers: production: @@ -58,7 +58,7 @@ channels: asyncapi: "2.0.0" info: title: Awesome API - description: A very well defined API + description: A very well-defined API version: "1.0" servers: production: @@ -80,7 +80,7 @@ The schema definition of the application headers must be of type “object”. ### asyncapi-info-contact-properties -The [asyncapi-info-contact](#asyncapi-info-contact) rule will ask you to put in a contact object, and this rule will make sure it's full of the most useful properties: `name`, `url` and `email`. +The [asyncapi-info-contact](#asyncapi-info-contact) rule will ask you to put in a contact object, and this rule will make sure it's full of the most useful properties: `name`, `url`, and `email`. Putting in the name of the developer/team/department/company responsible for the API, along with the support email and help-desk/GitHub Issues/whatever URL means people know where to go for help. This can mean more money in the bank, instead of developers just wandering off or complaining online. @@ -92,7 +92,7 @@ Putting in the name of the developer/team/department/company responsible for the asyncapi: "2.0.0" info: title: Awesome API - description: A very well defined API + description: A very well-defined API version: "1.0" contact: name: A-Team @@ -104,7 +104,7 @@ info: Info object should contain `contact` object. -Hopefully your API description document is so good that nobody ever needs to contact you with questions, but that is rarely the case. The contact object has a few different options for contact details. +Hopefully, your API description document is so good that nobody ever needs to contact you with questions, but that is rarely the case. The contact object has a few different options for contact details. **Recommended:** Yes @@ -176,7 +176,7 @@ info: ### asyncapi-message-examples -All `examples` in message object should follow by `payload` and `headers` schemas. +All `examples` in message object should follow `payload` and `headers` schemas. **Bad Example** @@ -261,7 +261,7 @@ Operation objects should have a description. ### asyncapi-operation-operationId-uniqueness -`operationId` must be unique across all the operations (except these one defined in the components). +`operationId` must be unique across all the operations (except the ones defined in the components). **Recommended:** Yes @@ -413,7 +413,7 @@ application/vnd.aai.asyncapi+yaml;version=2.0.0 At this point, explicitly setting `schemaFormat` is not supported by Spectral, so if you use it this rule will emit an info message and skip validating the payload. -Other formats such as OpenAPI Schema Object, JSON Schema Draft 07 and Avro will be added in various upcoming versions. +Other formats such as OpenAPI Schema Object, JSON Schema Draft 07, and Avro will be added in various upcoming versions. **Recommended:** Yes @@ -473,7 +473,7 @@ servers: ### asyncapi-server-not-example-com -Server URL should not point at example.com. +Server URL should not point to example.com. **Recommended:** No @@ -517,7 +517,7 @@ All server URL variables should be defined in the `variables` object of the serv ### asyncapi-servers -A non empty `servers` object is expected to be located at the root of the document. +A non-empty `servers` object is expected to be located at the root of the document. **Recommended:** Yes @@ -528,12 +528,12 @@ Tags alone are not very descriptive. Give folks a bit more information to work w ```yaml tags: - name: "Aardvark" - description: Funny nosed pig-head racoon. + description: Funny-nosed pig-head raccoon. - name: "Badger" description: Angry short-legged omnivores. ``` -If your tags are business objects then you can use the term to explain them a bit. An 'Account' could be a user account, company information, bank account, potential sales lead, anything. What is clear to the folks writing the document is probably not as clear to others. +If your tags are business objects then you can use the term to explain them a bit. An 'Account' could be a user account, company information, bank account, potential sales lead, or anything. What is clear to the folks writing the document is probably not as clear to others. ```yaml tags: From 730cd28a99de97c57d0d651e054b8c9861c2f7c3 Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Thu, 1 Sep 2022 17:18:35 -0500 Subject: [PATCH 11/13] docs(repo): grammarly pass for functions --- docs/reference/functions.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/reference/functions.md b/docs/reference/functions.md index 984d1d639..2e2e893d3 100644 --- a/docs/reference/functions.md +++ b/docs/reference/functions.md @@ -56,11 +56,11 @@ whitelisted-tags: ## falsy -The value should be `false`, `""`, `0`, `null` or `undefined`. Basically anything that would not trigger this: `if (!!targetVal)`. +The value should be `false`, `""`, `0`, `null` or `undefined`. Basically, anything that would not trigger this: `if (!!targetVal)`. ## length -Count the length of a string an or array, the number of properties in an object, or a numeric value, and define minimum and/or maximum values. +Count the length of a string or an array, the number of properties in an object, or a numeric value, and define minimum and/or maximum values. @@ -69,7 +69,7 @@ Count the length of a string an or array, the number of properties in an object, | min | the minimum length to match | number | no | | max | the maximum length to match | number | no | -At the very least `min` or `max` have to be provided. You can specify both as well. +At the very least `min` or `max` has to be provided. You can specify both as well. @@ -186,7 +186,7 @@ oas3-api-servers: ## truthy -The value should not be `false`, `""`, `0`, `null` or `undefined`. Basically anything that would not trigger this: `if (targetVal)`. +The value should not be `false`, `""`, `0`, `null`, or `undefined`. Basically, anything that would not trigger this: `if (targetVal)`. @@ -205,8 +205,7 @@ important-fields: ## defined -The value must be defined, meaning it must be anything but `undefined`. -It's the opposite of what undefined function does. +The value must be defined, meaning it must be anything but `undefined`. It's the opposite of what the undefined function does. ## undefined From d651a2bfd6f044c5eb872eb3f475ed56cc582c70 Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Thu, 1 Sep 2022 17:29:55 -0500 Subject: [PATCH 12/13] docs(repo): grammarly pass for openapi-rules --- docs/reference/openapi-rules.md | 36 ++++++++++++++++----------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/reference/openapi-rules.md b/docs/reference/openapi-rules.md index 37a1f91a6..d401c5e04 100644 --- a/docs/reference/openapi-rules.md +++ b/docs/reference/openapi-rules.md @@ -10,7 +10,7 @@ These rules apply to both OpenAPI v2.0, v3.0, and most likely v3.1, although the ### contact-properties -The [info-contact](#info-contact) rule will ask you to put in a contact object, and this rule will make sure it's full of the most useful properties: `name`, `url` and `email`. +The [info-contact](#info-contact) rule will ask you to put in a contact object, and this rule will make sure it's full of the most useful properties: `name`, `url`, and `email`. Putting in the name of the developer/team/department/company responsible for the API, along with the support email and help-desk/GitHub Issues/whatever URL means people know where to go for help. This can mean more money in the bank, instead of developers just wandering off or complaining online. @@ -22,7 +22,7 @@ Putting in the name of the developer/team/department/company responsible for the openapi: "3.0.2" info: title: Awesome API - description: A very well defined API + description: A very well-defined API version: "1.0" contact: name: A-Team @@ -72,7 +72,7 @@ TheBadModel: Info object should contain `contact` object. -Hopefully your API description document is so good that nobody ever needs to contact you with questions, but that is rarely the case. The contact object has a few different options for contact details. +Hopefully, your API description document is so good that nobody ever needs to contact you with questions, but that is rarely the case. The contact object has a few different options for contact details. **Recommended:** Yes @@ -144,7 +144,7 @@ info: ### no-\$ref-siblings -Prior to OpenAPI v3.1, keywords next to `$ref` were be ignored by most tooling, but not all. This leads to inconsistent experiences depending on what combinations of tools are used. As of v3.1 $ref siblings are allowed, so this rule will not be applied. +Before OpenAPI v3.1, keywords next to `$ref` were ignored by most tooling, but not all. This leads to inconsistent experiences depending on what combinations of tools are used. As of v3.1 $ref siblings are allowed, so this rule will not be applied. **Recommended:** Yes @@ -159,7 +159,7 @@ TheBadModel: ### no-eval-in-markdown -This rule protects against an edge case, for anyone bringing in description documents from third parties and using the parsed content rendered in HTML/JS. If one of those third parties does something shady like inject `eval()` JavaScript statements, it could lead to an XSS attack. +This rule protects against an edge case, for anyone bringing in description documents from third parties and using the parsed content rendered in HTML/JS. If one of those third parties does something shady like injecting `eval()` JavaScript statements, it could lead to an XSS attack. **Recommended:** Yes @@ -173,7 +173,7 @@ info: ### no-script-tags-in-markdown -This rule protects against a potential hack, for anyone bringing in description documents from third parties then generating HTML documentation. If one of those third parties does something shady like inject `