Skip to content

2-cli.md

Latest commit

 

History

History
176 lines (129 loc) · 7.83 KB

2-cli.md

File metadata and controls

176 lines (129 loc) · 7.83 KB

Spectral CLI

Once Spectral is installed and you have a ruleset, run Spectral via the command-line:

spectral lint petstore.yaml

Use this command to lint with a custom ruleset or one that's located in a different directory than your API document:

spectral lint petstore.yaml --ruleset myruleset.json

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 to match multiple files at once:

spectral lint ./reference/**/*.oas*.{json,yml,yaml}

Other options include:

      --version                  Show version number                                                           [boolean]
      --help                     Show help                                                                     [boolean]
  -e, --encoding                 text encoding to use
          [string] [choices: "utf8", "ascii", "utf-8", "utf16le", "ucs2", "ucs-2", "base64", "latin1"] [default: "utf8"]
  -f, --format                   formatters to use for outputting results, more than one can be given joining them with
                                 a comma
               [string] [choices: "json", "stylish", "junit", "html", "text", "teamcity", "pretty"] [default: "stylish"]
  -o, --output                   where to output results, can be a single file name, multiple "output.<format>" or
                                 missing to print to stdout                                                     [string]
      --stdin-filepath           path to a file to pretend that stdin comes from                                [string]
      --resolver                 path to custom json-ref-resolver instance                                      [string]
  -r, --ruleset                  path/URL to a ruleset file                                                     [string]
      --scoring-config           path/URL to a scoring config file                                              [string]
  -F, --fail-severity            results of this level or above will trigger a failure exit code
                                                  [string] [choices: "error", "warn", "info", "hint"] [default: "error"]
  -D, --display-only-failures    only output results equal to or greater than --fail-severity [boolean] [default: false]
      --ignore-unknown-format    do not warn about unmatched formats                          [boolean] [default: false]
      --fail-on-unmatched-globs  fail on unmatched glob patterns                              [boolean] [default: false]
  -v, --verbose                  increase verbosity                                                            [boolean]
  -q, --quiet                    no logging - output only                                                      [boolean]

The Spectral CLI supports loading documents as YAML or JSON, and validation of OpenAPI v2/v3 documents via the built-in ruleset.

Using a Ruleset File

If you don't specify a ruleset file with the --ruleset parameter, the Spectral CLI looks for a ruleset file called .spectral.yml, .spectral.yaml, .spectral.json or .spectral.js in the current working directory. Spectral won't lint the document if no ruleset is specified and no default ruleset file is found.

Here you can build a custom ruleset, or extend and modify the core rulesets:

Scoring the API

Scoring an API definition is a way to understand in a high level, how compliant is the API definition with the rulesets provided. This helps teams to understand the quality of the APIs regarding the definition.

The scoring is produced in two different metrics:

  • A number scoring. Who cames as substracting from 100% from any error or warning
  • A letter, who groups numeric scorings in letters from A (better) to any

Also it introduces a quality gate, were an API scoring below the specific threshold will fail in a pipeline.

Enabling scoring is done using a new parameter called --scoring-config and the scoring configuration file, where you can define how an error or a warning affects to the scoring

Usage:

 spectral lint ./reference/**/*.oas*.{json,yml,yaml} --ruleset mycustomruleset.js --scoring-config ./scoringFile.json

Heres an example of this scoringFile config file:

    {
      "scoringSubtract":
        {
          "error":
           {
             1:55,
             2:65,
             3:75,
             6:85,
             10:95
           }
          "warn":
           {
             1:3,
             2:7,
             3:10,
             6:15,
             10:18
           }
        },
      "scoringLetter":
        {
          "A":75,
          "B":65,
          "C":55,
          "D":45,
          "E":0
        },
      "threshold":50,
      "warningsSubtract": true,
      "uniqueErrors": false
    }

Where:

  • scoringSubtract : An object with a key/value pair objects for every result level we want to subtract percentage, with the percentage to subtract from number of results on every result type
  • scoringLetter : An object with key/value pairs with scoring letter and scoring percentage, that the result must be greater , for this letter
  • threshold : A number with minimum percentage value to provide valid the file we are checking
  • warningsSubtract : A boolean to setup if accumulate the result types to less the scoring percentage or stop counting on most critical result types
  • uniqueErrors : A boolean to setup a count with unique errors or with all of them. An error is considered unique if its code and message have not been seen yet

Example:

With previous scoring config file, if we have:

1 error, the scoring is 45% and D
2 errors, the scoring is 35% and E
3 errors, the scoring is 25% and E
4 errors, the scoring is 25% and E
and so on

Output:

Below your output log you can see the scoring, like:

✖ SCORING: A (93%)

Error Results

Spectral has a few different error severities: error, warn, info, and hint, and they're in order from highest to lowest. By default, all results are shown regardless of severity, but since v5.0, only the presence of errors causes 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 returns a failure status code of 1 for any info results or higher. Using --fail-severity=warn causes a failure status code for errors or warnings.

Changing the fail severity wont' affect output. To change the results Spectral CLI prints to the screen, add the --display-only-failures switch (or just -D for short). This removes 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 the PROXY environment variable:

PROXY=<<PROXY_SERVER_ADDRESS>> spectral lint spec.yaml

Custom $ref Resolving

To customize $ref resolving, use the --resolver flag and pass a path to the JS file exporting a custom instance of json-ref-resolver Resolver.

Example

Assuming the filename is called my-resolver.js and the content looks as follows, the path should look like: --resolver=./my-resolver.js.

const { Resolver } = require("@stoplight/json-ref-resolver");

module.exports = new Resolver({
  resolvers: {
    // pass any resolver for the protocol you need
  },
});

You can learn more about $ref resolving in the JS section.