Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(rulesets): add Arazzo to rulesets docs #2703

Merged
merged 3 commits into from
Oct 4, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/getting-started/1-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 3 additions & 2 deletions docs/getting-started/3-rulesets.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
1 change: 1 addition & 0 deletions docs/guides/2-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
3 changes: 2 additions & 1 deletion docs/guides/4-custom-rulesets.md
Original file line number Diff line number Diff line change
@@ -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).

Expand All @@ -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)
Expand Down