An ultra-super-fast, lightweight OpenAPI linter and quality checking tool, written in golang and inspired by Spectral.
It's also compatible with existing Spectral rulesets.
Install using homebrew tap
brew install daveshanley/vacuum/vacuum
Install using npm
npm i -g @quobix/vacuum
Install using yarn
yarn global add @quobix/vacuum
curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
Install using Docker
The image is available at: https://hub.docker.com/r/dshanley/vacuum
docker pull dshanley/vacuum
To run, mount the current working dir to the container and use a relative path to your spec, like so
docker run --rm -v $PWD:/work:ro dshanley/vacuum lint <your-openapi-spec.yaml>
Alternatively, you can pull it from
Github packages.
To do that, replace dshanley/vacuum
with ghcr.io/daveshanley/vacuum
in the above commands.
If your company is using vacuum
, please considering supporting this project,
like our very kind sponsors:
![scalar](https://raw.githubusercontent.com/lyda/vacuum/main/.github/sponsors/scalar-light.png)
![scalar](https://raw.githubusercontent.com/lyda/vacuum/main/.github/sponsors/zuplo-light.png)
Need help? Have a question? Want to share your work? Join our discord and come say hi!
🔥 New in v0.7+
🔥 : Hard Mode.
Want to lint your spec with the most strict ruleset possible? Now you can! Use the -z
/ --hard-mode
flag to enable
v0.6+
: Sharable / distributed rulesets now available.
Want to share / extend / distribute your own rulesets? Now you can!
Learn more about sharable rulesets
v0.5+
: Multi-file linting now available for the lint
command.
Want to lint multiple files at once? Now you can!
vacuum lint file1.json path/to/file2.yaml file3.json
Want to suck in a ton of files? Use a glob pattern!
vacuum lint some/path/**/*.yaml
v0.3+
: Custom JavaScript Functions are now available out of the box.
Write custom functions in JavaScript and use them in any ruleset. No need to compile golang code to extend vacuum anymore!
Learn more about building custom JavaScript functions.
v0.2+
: OWASP API rules are now available out of the box.
Learn more about enabling OWASP API rules.
See all the documentation at https://quobix.com/vacuum
- Installing vacuum
- About vacuum
- Why should you care?
- Concepts
- FAQ
- CLI Commands
- Developer API
- Rules
- Functions
- Understanding RuleSets
vacuum can suck all the lint of a 5mb OpenAPI spec in milliseconds.
Designed to reliably lint OpenAPI specifications, very, very quickly. Including very large ones. Spectral can be quite slow when used as an API and does not scale for enterprise applications.
vacuum will tell you what is wrong with your spec, why, where and how to fix it.
vacuum will work at scale and is designed as a CLI (with a web or console UI) and a library to be consumed in other applications.
vacuum comes with an interactive dashboard (vacuum dashboard <your-openapi-spec.yaml>
) allowing you to explore
rules and violations in a console, without having to scroll through thousands of results.
vacuum can generate an easy to navigate and understand HTML report. Like the dashboard you can explore broken rules and violations, but in your browser.
No external dependencies, the HTML report will run completely offline.
Supports OpenAPI Version 2 (Swagger) and Version 3+
You can use either YAML or JSON, vacuum supports both formats.
Vacuum can be used with pre-commit.
To do that, add to your .pre-commit-config.yaml
:
repos:
- repo: https://github.com/daveshanley/vacuum
rev: # a tag or a commit hash from this repo, see https://github.com/daveshanley/vacuum/releases
hooks:
- id: vacuum
See the hook definition here for details on what options the hook uses and what files it checks by default.
If no filenames or more than one filename in your repository matches the default files
pattern in the hook definition,
the pattern needs to be overridden in your config so that it matches exactly one filename to lint at a time.
To lint multiple files, specify the hook multiple times with the appropriate overrides.
./vacuum html-report <your-openapi-spec.yaml | vacuum-report.json.gz> <report-name.html>
You can replace report-name.html
with your own choice of filename. Open the report
in your favorite browser and explore the results.
./vacuum lint -d <your-openapi-spec.yaml>
./vacuum lint -d <spec1.yaml> <spec2.yaml> <spec3.yaml>
./vacuum lint -d some/path/**/*.yaml
./vacuum lint -d -s <your-openapi-spec.yaml>
./vacuum lint -d -e <your-openapi-spec.yaml>
./vacuum lint -d -c schemas <your-openapi-spec.yaml>
The options here are:
examples
operations
information
descriptions
schemas
security
tags
validation
owasp
If you're already using Spectral JSON reports, and you want to use vacuum instead, use the spectral-report
command
./vacuum spectral-report <your-openapi-spec.yaml> <report-output-name.json>
The report file name is optional. The default report output name is vacuum-spectral-report.json
Vacuum reports are complete snapshots in time of a linting report for a specification. These reports can be 'replayed'
back through vacuum. Use the dashboard
or the html-report
commands to 'replay' the report and explore the results
as they were when the report was generated.
./vacuum report -c <your-openapi-spec.yaml> <report-prefix>
The default name of the report will be vacuum-report-MM-DD-YY-HH_MM_SS.json
. You can change the prefix by supplying
it as the second argument to the report
command.
Ideally, you should compress the report using -c
. This shrinks down the size significantly. vacuum automatically
recognizes a compressed report file and will deal with it automatically when reading.
When using compression, the file name will be
vacuum-report-MM-DD-YY-HH_MM_SS.json.gz
. vacuum uses gzip internally.
This is an early, but working console UI for vacuum. The code isn't great, it needs a lot of clean up, but if you're interested in seeing how things are progressing, it's available.
./vacuum dashboard <your-openapi-spec.yaml | vacuum-report.json.gz>
If you're already using Spectral and you have your own custom ruleset, then you can use it with vacuum!
The lint
, dashboard
and spectral-report
commands all accept a -r
or --ruleset
flag, defining the path to your ruleset file.
All rules turned off
./vacuum lint -r rulesets/examples/norules-ruleset.yaml <your-openapi-spec.yaml>
Only recommended rules
./vacuum lint -r rulesets/examples/recommended-ruleset.yaml <your-openapi-spec.yaml>
Enable specific rules only
./vacuum lint -r rulesets/examples/specific-ruleset.yaml <your-openapi-spec.yaml>
Custom rules
./vacuum lint -r rulesets/examples/custom-ruleset.yaml <your-openapi-spec.yaml>
_All rules, all of them!
./vacuum lint -r rulesets/examples/all-ruleset.yaml <your-openapi-spec.yaml>
You can configure vacuum using a configuration file named vacuum.conf.yaml
By default, vacuum searches for this file in the following directories
- Working directory
$XDG_CONFIG_HOME
${HOME}/.config
You can also specify a path to a file using the --config
flag
Global flags are configured as top level nodes
time: true
base: 'http://example.com'
...
Command specific flags are configured under a node with the commands name
...
lint:
silent: true
...
You can configure global vacuum flags using environmental variables in the form of: VACUUM_<flag>
If a flag, has a -
in it, replace with _
Logo gopher is modified, originally from egonelbre