From a06c3e237075d3e0d8010e8e7d085220a4db058f Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Sat, 28 Sep 2024 11:01:58 +0100 Subject: [PATCH 1/2] chore(rulesets): add Arazzo to rulesets docs --- docs/guides/4-custom-rulesets.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guides/4-custom-rulesets.md b/docs/guides/4-custom-rulesets.md index 1fd70f995..14b42b707 100644 --- a/docs/guides/4-custom-rulesets.md +++ b/docs/guides/4-custom-rulesets.md @@ -1,6 +1,6 @@ # Rulesets -Spectral comes with two rulesets built-in: [OpenAPI](../reference/openapi-rules.md) and [AsyncAPI](../reference/asyncapi-rules.md). They're good starting points, but the true power of Spectral comes with customizing and creating a ruleset that fits your project or organization. Creating a ruleset can help you and your team improve your API design and API development process, and help you create better APIs. +Spectral comes with three rulesets built-in: [OpenAPI](../reference/openapi-rules.md), [AsyncAPI](../reference/asyncapi-rules.md), and [Arazzo](../reference/arazzo-rules.md). They're good starting points, but the true power of Spectral comes with customizing and creating a ruleset that fits your project or organization. Creating a ruleset can help you and your team improve your API design and API development process, and help you create better APIs. Let's look through the keywords that make up a ruleset, so you can learn how to tweak a distributed ruleset to work for you, or make your own ruleset from scratch to power your organizations [API Style Guide](https://stoplight.io/api-style-guides-guidelines-and-best-practices/?utm_source=github&utm_medium=spectral&utm_campaign=docs). @@ -22,6 +22,7 @@ Rules are the most important part of a ruleset. For more details on rules and it Formats are an optional way to specify which API description formats a rule, or ruleset, is applicable to. Currently Spectral supports these formats: +- `arazzo1_0` (Arazzo v1.0.x) - `aas2` (AsyncAPI v2.x) - `aas2_0` (AsyncAPI v2.0.0) - `aas2_1` (AsyncAPI v2.1.0) From 49266430e0ca2c7c39e0a2ec98692782b6acf825 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Sat, 28 Sep 2024 11:54:25 +0100 Subject: [PATCH 2/2] chore(rulesets): add missing Arazzo docs --- docs/getting-started/1-concepts.md | 4 ++-- docs/getting-started/3-rulesets.md | 5 +++-- docs/guides/2-cli.md | 1 + 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/getting-started/1-concepts.md b/docs/getting-started/1-concepts.md index 7318a7d5b..b510022a2 100644 --- a/docs/getting-started/1-concepts.md +++ b/docs/getting-started/1-concepts.md @@ -8,9 +8,9 @@ To achieve this, Spectral has three key concepts: - **Functions** accept a value and return issues if the value is incorrect. - **Rulesets** act as a container for rules and functions. -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. +Spectral comes bundled with a [set of core functions](../reference/functions.md) and rulesets for working with [OpenAPI v2 and v3](./4-openapi.md), [AsyncAPI v2](./5-asyncapi.md), and [Arazzo v1](./6-arazzo.md) that you can chose to use or extend, but Spectral is about far more than just checking your OpenAPI/AsyncAPI/Arazzo 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 several can be found on [API Stylebook](http://apistylebook.com/), but most of these rules could be automated with Spectral. For example: +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, "Center for Enablement", 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. For example: - Paths must be `/kebab-case` ([more ideas for URL rules](https://blog.stoplight.io/consistent-api-urls-with-openapi-and-style-guides)) - HTTP Basic isn't allowed diff --git a/docs/getting-started/3-rulesets.md b/docs/getting-started/3-rulesets.md index 59a018b04..735a8f930 100644 --- a/docs/getting-started/3-rulesets.md +++ b/docs/getting-started/3-rulesets.md @@ -10,15 +10,16 @@ Rules take certain parameters and then call functions on parts of another YAML o The fastest way to create a ruleset is to use the `extends` property to leverage an existing ruleset. -Spectral comes with two built-in rulesets: +Spectral comes with three built-in rulesets: - `spectral:oas` - [OpenAPI v2/v3 rules](./4-openapi.md) - `spectral:asyncapi` - [AsyncAPI v2 rules](./5-asyncapi.md) +- `spectral:arazzo` - [Arazzo v1 rules](./6-arazzo.md) To create a ruleset that extends both rulesets, open your terminal and run: ```bash -echo 'extends: ["spectral:oas", "spectral:asyncapi"]' > .spectral.yaml +echo 'extends: ["spectral:oas", "spectral:asyncapi", "spectral:arazzo"]' > .spectral.yaml ``` The newly created ruleset file can then be used to lint any OpenAPI v2/v3 or AsyncAPI descriptions using the `spectral lint` command: diff --git a/docs/guides/2-cli.md b/docs/guides/2-cli.md index f0edd3e7c..69e93b223 100644 --- a/docs/guides/2-cli.md +++ b/docs/guides/2-cli.md @@ -60,6 +60,7 @@ Here you can build a [custom ruleset](../getting-started/3-rulesets.md), or exte - [OpenAPI ruleset](../reference/openapi-rules.md) - [AsyncAPI ruleset](../reference/asyncapi-rules.md) +- [Arazzo ruleset](../reference/arazzo-rules.md) > If you use rules created or updated in a hosted [Stoplight API project](https://docs.stoplight.io/docs/platform/branches/pam-716-updated-landing-page/c433d678d027a-create-rules) with the Spectral CLI, you must publish the project from Stoplight before rule updates are used for linting.