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

docs: SVG for the readme and a quick go at cli #299

Merged
merged 16 commits into from
Jul 9, 2019
Merged
110 changes: 43 additions & 67 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,117 +5,93 @@
[![Build Status](https://dev.azure.com/vncz/vncz/_apis/build/status/stoplightio.spectral?branchName=develop)](https://dev.azure.com/vncz/vncz/_build/latest?definitionId=4&branchName=develop)
[![CircleCI](https://circleci.com/gh/stoplightio/spectral.svg?style=svg)](https://circleci.com/gh/stoplightio/spectral)

A flexible JSON object linter with out of the box support for OpenAPI v2 and v3
A flexible JSON linter with out of the box support for OpenAPI v2 and v3.

![Demo of Spectral linting an OpenAPI document from the CLI](./docs/demo.svg)

## Features

- Create custom rules to lint _any JSON object_
- Use JSON paths to apply rules / functions to specific parts of your JSON objects
- Built-in set of functions to help [build custom rules](#creating-a-custom-rule). Functions include pattern checks, parameter checks, alphabetical ordering, a specified number of characters, provided keys are present in an object, etc
- [Create custom functions](#creating-a-custom-function) for advanced use cases
- Optional ready to use rules and functions to validate and lint [OpenAPI v2 _and_ v3 documents](#example-linting-an-openapi-document)
- Validate JSON with [Ajv](https://github.com/epoberezkin/ajv)
- Create custom rules to lint JSON or YAML objects
- Ready to use rules to validate and lint OpenAPI v2 _and_ v3 documents
- Use JSON path to apply rules to specific parts of your objects
- Built-in set of functions to help [create custom rules](./docs/rulesets.md). Functions include pattern checks, parameter checks, alphabetical ordering, a specified number of characters, provided keys are present in an object, etc.
- Create custom functions for advanced use cases
- Validate JSON with [Ajv](https://www.npmjs.com/package/ajv)

## Installation

### Local Installation

```bash
npm install @stoplight/spectral
```
Spectral's CLI can be installed either via npm or yarn

### Global Installation
### npm

```bash
npm install -g @stoplight/spectral
# or
yarn global add @stoplight/spectral
```

Supports Node v8.3+ and modern browsers.

### Executable binaries

For users without Node and/or NPM/Yarn, we provide standalone packages for all major platforms. We also provide a shell script to auto download the executable based on your operating system:

`curl -L https://raw.githack.com/stoplightio/spectral/master/install.sh | sh`
### Docker Image

Note, the binaries are *not* auto-updatable, therefore you will need to download a new version on your own.

#### Installing binaries system-wide

##### Linux
Spectral is avaiable as a Docker image as well

```bash
sudo mv ./spectral-linux /usr/local/bin/spectral
```

You may need to restart your terminal.
Now, `spectral` command will be accessible in your terminal.

Head over to [releases](https://github.com/stoplightio/spectral/releases) for the latest binaries.


### Docker
```bash
docker run --rm -it stoplight/spectral lint "${URL}"`
```

[Executable binaries](#executable-binaries) are also available.

## Usage

### CLI

Spectral can be run via the command-line:

```bash
spectral lint petstore.yaml
```

Other options include:

``` text
-e, --encoding=encoding text encoding to use
-f, --format=json|stylish formatter to use for outputting results
-h, --help show CLI help
-m, --maxResults=maxResults deprecated: use --max-results instead
-o, --output=output output to a file instead of stdout
-q, --quiet no logging - output only
-r, --ruleset=ruleset path to a ruleset file (supports remote files)
-s, --skip-rule=skip-rule ignore certain rules if they are causing trouble
-v, --verbose increase verbosity
--max-results=max-results [default: all] maximum results to show
```
Spectral can be installed and used via your terminal. Take a look at the [CLI docs](./docs/cli.md).

> Note: The Spectral CLI supports both YAML and JSON.
### Examples

Currently, Spectral CLI CLI supports validation of OpenAPI documents and lints them based on our default ruleset, or you can provide [your own rulesets](docs/rulesets.md).
- [Adding a rule](./docs/rulesets.md#adding-a-rule)
- [Adding to the recommended OpenAPI rules](./docs/rulesets.md#adding-to-the-recommended-openapi-rules)
- [Enabling specific OpenAPI rules](./docs/rulesets.md#enabling-specific-openapi-rules)
- [Disabling specific OpenAPI rules](./docs/rulesets.md#disabling-specific-openapi-rules)
- [Changing the severity of a rule](./docs/rulesets.md#changing-the-severity-of-a-rule)

## Concepts

There are three key concepts in Spectral: **Rulesets**, **Rules** and **Functions**.
There are three key concepts in Spectral: **Rulesets**, **Rules**, and **Functions**.

- **Ruleset** is a container for a collection of rules and functions.
- **Rule** filters your object down to a set of target values, and specify the function that should evaluate those values.
- **Function** accept a value and return issue(s) if the value is incorrect.
- **Rulesets** act as a container for rules and functions.
- **Rules** filter your object down to a set of target values, and specify the function that is used to evaluate those values.
- **Functions** accept a value and return issue(s) if the value is incorrect.

Think of a set of **rules** and **functions** as a flexible and customizable style guide for your JSON objects.
Think of a **Spectral ruleset** as a flexible and customizable style guide for your JSON objects.

## Programmatic usage

Spectral is written in TypeScript (JavaScript) and can be used directly for when you need to use Spectral programmatically. Take a look at our ["JavaScript API documentation"](docs/js-api.md).
Spectral is written in TypeScript (the compiled to JavaScript) and can be used directly for when you need to use Spectral programmatically. Take a look at our ["JavaScript API documentation"](docs/js-api.md).

## FAQs

**How is this different than [Ajv](https://github.com/epoberezkin/ajv)?**
#### How is this different than [Ajv](https://www.npmjs.com/package/ajv)?

Ajv is a JSON Schema validator, not a linter. Spectral does expose a `schema` function that you can use in your rules to validate all or part of the target object with JSON Schema (Ajv is used under the hood). However, Spectral also provides a number of other functions and utilities that you can use to build up a linting ruleset to validates things that JSON Schema is not well suited for.

**I want to lint my OpenAPI documents but don't want to implement Spectral right now.**
#### I want to lint my OpenAPI documents but don't want to implement Spectral right now.

No problem! A hosted version of Spectral comes **free** with the Stoplight platform. Sign up for a free account [here](https://stoplight.io/?utm_source=github&utm_campaign=spectral).

**What is the difference between Spectral and [Speccy](https://github.com/wework/speccy)?**
#### What is the difference between Spectral and [Speccy](https://github.com/wework/speccy)?

With Spectral, lint rules can be applied to _any_ JSON object. Speccy is designed to work with OpenAPI v3 only. The rule structure is different between the two. Spectral uses [JSONPath](http://goessner.net/articles/JsonPath/) `path` parameters instead of the `object` parameters (which are OpenAPI specific). Rules are also more clearly defined (thanks to TypeScript typings) and now require specifying a `type` parameter. Some rule types have been enhanced to be a little more flexible along with being able to create your own rules based on the built-in and custom functions.

### Executable binaries

For users without Node and/or NPM/Yarn, we provide standalone packages for [all major platforms](https://github.com/stoplightio/spectral/releases). We also provide a shell script to auto download the executable based on your operating system:

```bash
curl -L https://raw.githack.com/stoplightio/spectral/master/install.sh | sh
```

Note, the binaries are *not* auto-updatable, therefore you will need to download a new version on your own.

## Contributing

If you are interested in contributing to Spectral itself, check out our [contributing docs](CONTRIBUTING.md) to get started.
Expand Down
25 changes: 25 additions & 0 deletions docs/cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Spectral CLI

One installed, Spectral can be run via the command-line:

```bash
spectral lint petstore.yaml
```

Other options include:

``` text
-e, --encoding=encoding text encoding to use
-f, --format=json|stylish formatter to use for outputting results
-h, --help show CLI help
-o, --output=output output to a file instead of stdout
-q, --quiet no logging - output only
-r, --ruleset=ruleset path to a ruleset file (supports remote files)
-s, --skip-rule=skip-rule ignore certain rules if they are causing trouble
-v, --verbose increase verbosity
--max-results=max-results [default: all] maximum results to show
```

> Note: The Spectral CLI supports both YAML and JSON.

Currently, Spectral CLI supports validation of OpenAPI documents and lints them based on our default ruleset, or you can create and use [your own rulesets](./rulesets.md).
1 change: 1 addition & 0 deletions docs/demo.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
153 changes: 120 additions & 33 deletions docs/rulesets.md
Original file line number Diff line number Diff line change
@@ -1,41 +1,128 @@
---
title: Spectral Rulesets
tags:
- Documentation
- Rulesets
---
# Spectral Rulesets

Rulesets are a container for collections of rules. These rules are essentially calling functions Spectral, and by taking parameters you can make these functions do whatever you want.
Rulesets are a container for collections of rules. These rules are taking parameters, and calling functions on certain parts of the JSON object being linted.

First the rule filters your object (JSON/YAML file) down to a set of target values, and then list what function arguments should be passed in.
## CLI Usage

## Usage
When you run the `spectral lint my-document.json` CLI command, Spectral will automatically apply the built in OpenAPI v2 or v3 ruleset if appropriate.

```bash
spectral lint foo.yaml --ruleset=path/to/acme-company-ruleset.yaml --ruleset=http://example.com/acme-common-ruleset.yaml
To customize the rules that are applied, simply create a `spectral.yml` in the same directory that you are running the `spectral lint` command from and it will automatically be used.

## Ruleset Examples

Spectral currently support ruleset files in both `yaml` and `json` formats.

### Adding a rule

Add your own rules under the `rules` property in your `spectral.yml` ruleset file.

**spectral.yml**

```yaml
rules:
my-rule-name:
description: Tags must have a description.
given: $.tags[*]
severity: error
then:
field: description
function: truthy
```

The example above adds a single rule that checks that tags objects have a description property defined.

Running `spectral lint` on the following object with the rulset above will result in an error being reported, since the tag does not have a description:

```json
{
"tags": [{
"name": "animals"
}]
}
```

While running it with this object will succeed:

```json
{
"tags": [{
"name": "animals",
"description": "come in all shapes and sizes"
}]
}
```

### Adding to the recommended OpenAPI rules

Spectral comes with two built in rulesets - one for OpenAPI v2 (`spectral:oas2`), and one for OpenAPI v3 (`spectral:oas3`). Use the `extends` property in your ruleset file to build upon or customize other rulesets.

**spectral.yml**

```yaml
extends: spectral:oas2
rules:
my-rule-name:
description: Tags must have a description.
given: $.tags[*]
then:
field: description
function: truthy
```

The example above will apply the recommended rules from the built in OpenAPI v2 ruleset AND apply the custom `my-rule-name` rule.

### Enabling specific OpenAPI rules

Sometimes you might want to apply specific rules from another ruleset. Use the `extends` property, and pass `off` as the second argument in order to load add the rules from another ruleset, but disable them all by default. This allows you to pick and choose which rules you would like to enable.

**spectral.yml**

```yaml
extends: [[spectral:oas2, off]]
rules:
# This rule is defined in the spectral:oas2 ruleset. We're passing `true` to turn it on and inherit the severity defined in the spectral:oas2 ruleset.
operation-operationId-unique: true
```

The example above will run the two rules we enabled, since we pass `off` to disable all rules by default when extending the `spectral:oas2` ruleset.

### Disabling specific OpenAPI rules

This example shows the opposite of the `Enabling specific OpenAPI rules` example. Sometimes you might want to enable all rules by default, and disable a few.

**spectral.yml**

```yaml
extends: [[spectral:oas2, all]]

# we could also just extend spectral:oas2 like this, which would only run the recommended rules (rather than every single rule)
# extends: spectral:oas2

rules:
operation-operationId-unique: false
```

## Example Ruleset
The example above will run all of the rules defined in the `spectral:oas2` ruleset (rather than the default behavior that runs just the recommended ones), with two exceptions - we turned `operation-operationId-unique` and `operation-2xx-response` off.

### Changing the severity of a rule

We currently support ruleset files in both `yaml` and `json` formats.
**spectral.yml**

```yaml
extends:
- https://acme.com/ruleset.json
- /path/to/ruleset.yaml
extends: spectral:oas2
rules:
rule-name:
given: $..parameters[*]
then:
field: description
function: truthy
operation-2xx-response: warn
```

The example above will run the recommended rules from the `spectral:oas2` ruleset, but report `operation-2xx-response` as a warning rather than as an error (as is the default behavior in the `spectral:oas2` ruleset).

Available severity levels are `error`, `warn`, `info`, and `off`.

## Rules

Rules are highly configurable. There are only few required parameters but the optional ones gives powerful flexibility. Please see the following type tables for more information.

*TODO: generate this table automatically from the TS file.*
<!-- *TODO: generate this table automatically from the TS file.* -->

<table>
<thead>
Expand Down Expand Up @@ -85,7 +172,7 @@ Rules are highly configurable. There are only few required parameters but the op
<td>recommended</td>
<td><code>boolean</code></td>
<td>should the rule be enabled by default?</td>
</tr>
</tr>
<tr>
<td>when</td>
<td><code><a href="#when">When</a></code></td>
Expand All @@ -104,7 +191,7 @@ Rules are highly configurable. There are only few required parameters but the op
<th>Description</th>
</tr>
</thead>
<tbody>
<tbody>
<tr>
<td>function</td>
<td><code>string</code></td>
Expand All @@ -114,7 +201,7 @@ Rules are highly configurable. There are only few required parameters but the op
<td>field</td>
<td><code>string</code></td>
<td>Name of the field to narrow by or special <code>@key</code> value. If a field name is provided, the function will receive value of that field. If <code>@key</code> is provided, the function will receive its key.<br/>Example: if the target object is an oas object and given = <code>$..responses[*]</code>, then <code>@key</code> would be the response code (200, 400, etc) and <code>description</code> would be the value of each response's description</td>
</tr>
</tr>
<tr>
<td>functionOptions</td>
<td><code>Object</code></td>
Expand All @@ -133,7 +220,7 @@ Rules are highly configurable. There are only few required parameters but the op
<th>Description</th>
</tr>
</thead>
<tbody>
<tbody>
<tr>
<td>field</td>
<td><code>string</code></td>
Expand All @@ -158,12 +245,12 @@ $ spectral lint some-oas.yaml --ruleset acme-company.json

Reading ruleset

/rules/rule-without-given-nor-them should have required property 'given'
/rules/rule-without-given-nor-them should have required property 'then'
/rules/rule-with-invalid-enum/severity should be number
/rules/rule-with-invalid-enum/severity should be equal to one of the allowed values
/rules/rule-with-invalid-enum/type should be equal to one of the allowed values
/rules/rule-without-given-nor-them should have required property 'given'
/rules/rule-without-given-nor-them should have required property 'then'
/rules/rule-with-invalid-enum/severity should be number
/rules/rule-with-invalid-enum/severity should be equal to one of the allowed values
/rules/rule-with-invalid-enum/type should be equal to one of the allowed values
```

These errors should look just like errors you get from Spectral when an API description is invalid,
so use them to fix your rules in the same way.
These errors should look just like errors you get from Spectral when an API description is invalid,
so use them to fix your rules in the same way.