The fastest way to see something useful is to print something out to the console.

vacuum lint my-openapi-spec.yaml

This will print a summary of your linting results. The lint command will use the Recommended RuleSet.

Just want to try things out?

If you don’t have an OpenAPI spec and you want to see something, you can run it against one of the test specifications. A good one to try is the petstorev3.json specification.

vacuum lint model/test_files/petstorev3.json

Linting multiple files

From v0.5.0+ The lint command accepts multiple OpenAPI files as inputs, either as a glob pattern, or as a list of files.

vacuum lint openapi-file1.json openapi-file2.json openapi-file3.json

Or as a glob pattern

vacuum lint ./model/*/*.yaml

In v0.9.6 a new flag was added to allow for globbed files to be linted. This is useful for CI/CD pipelines that do not have a shell that provides the ability to use a glob pattern.

--globbed-files accepts a glob pattern and will lint all files that match the pattern.

vacuum lint --globbed-files="*/**/bu*.openapi.yaml" model/test_files/badref-burgershop.openapi.yaml

Available Flags

lint supports the following flags

Short Full Input Description
-d –details bool Show full details of the linting report
-c –category string Used with -d, Show a single category of results
-e –errors bool Used with -d, Show only reported errors
-x –silent bool Show no output, except for the linting result
-s –snippets bool Used with -d, shows highlighted code in console
-n –fail-severity string Set the level at which an error return code is thrown (defaults to error)
-q –no-style bool Disable color and style console output (useful for CI/CD)
-h –help bool Show help screen and all flag details
-m –no-message bool Hide the ‘message’ column when showing details via -d
-b –no-banner bool Hide the welcome / version banner
-a –all-results bool Show all results (regardless of number) when showing details via -d
–ignore-polymorph-circle-ref bool Ignore polymorphic based circular references
–ignore-array-circle-ref bool Show array based circular references based
–globbed-files bool Use a glob pattern to lint multiple files
–no-clip bool Do not truncate/clip long message or JSON path output

Global Flags

lint supports the following global flags

Short Full Input Description
-r –ruleset string Use an existing ruleset file for linting
-t –time bool Show how long it took to lint the spec in (ms)
-p –base string Base URL or Base working directory to use for relative references
-u –remote string Load remote references automatically if possible (default is true)
-k –skip-check string Skip checking for a valid OpenAPI document, useful for linting fragments or non-OpenAPI documents
-g –timeout string How long (in seconds to wait) for a rule before it times out (default is 5 seconds)
-z –hard-mode string Enable every single built-in rule (including OWASP). Only for adventurers and brave souls.
–ext-refs bool Allow $ref pointers inside extension objects (x-) to be looked up

Full flags begin with a double hyphen.

Examples

Want something easy to copy and paste?

Using an existing RuleSet

vacuum lint -r rulesets/examples/specific-ruleset.yaml \ model/test_files/petstorev3.json

Single category

vacuum lint -d -c operations model/test_files/petstorev3.json

Single category with snippets

vacuum lint -d -s -c operations model/test_files/petstorev3.json

Only show errors

vacuum lint -d -e model/test_files/asana.yaml

Fail severity

vacuum can be set to return a non-zero exit code if the linting results contain a severity level that is equal to or greater than the --fail-severity / -n flag. This is useful for CI/CD pipelines.

There are three levels are supported:

Level Description
error Return a non-zero exit code if any errors are found
warn Return a non-zero exit code if any errors or warnings are found
info Return a non-zero exit code if any errors, warnings, or infos are found

Setting the --fail-severity flag to warn will return a non-zero exit code if any errors or warnings are found.

vacuum lint --fail-severity warn model/test_files/asana.yaml