`bash curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh `
$3
To avoid GitHub API rate limiting in automated environments, set a GitHub token:
`bash
Using repository token (GitHub Actions)
GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
Using personal access token
GITHUB_TOKEN=your_github_token curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh `
#### GitHub Actions example
`yaml - name: Install vacuum env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Increases rate limit from 60 to 5000 requests/hour run: | curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh `
> Note: The GitHub token prevents intermittent installation failures in CI/CD environments caused by API rate limiting. > No additional permissions are required, the token only accesses public repository information.
The image is available at: https://hub.docker.com/r/dshanley/vacuum
` docker pull dshanley/vacuum `
> Multi-platform support: Docker images are available for both
linux/amd64 and linux/arm64 architectures, including native ARM64 support for Apple Silicon Macs.
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 ` Alternatively, you can pull it from Github packages. To do that, replace dshanley/vacuum with ghcr.io/daveshanley/vacuum in the above commands.
Run with Go
If you have go >= 1.16 installed, you can use
go run to build and run it:` go run github.com/daveshanley/vacuum@latest lint `
---
Sponsors
If your company is using vacuum, please considering supporting this project, like our _very kind_ sponsors, past and present:
Need help? Have a question? Want to share your work? Join our discord and come say hi!
Documentation
š„ New in
v0.23 š„: OpenAPI Overlay Support
Ever needed to tweak an OpenAPI spec for different environments without maintaining multiple copies?
Maybe swap out server URLs between dev, staging, and production? Or perhaps strip out internal endpoints before publishing the API docs?
OpenAPI Overlays are the answer. They let us make non-destructive modifications to specs using JSONPath expressions to target exactly what we want to change. vaccum now supports a new
Do you want to call remote APIs in your vacuum javascript functions? What about async processing or the ability to use Promises?
vacuum now has its own event loop and will happily support
async and await. Combined with a full implementation of Fetch.
Also added Batch Mode. This allows custom functions to receive the entire list of nodes, instead of firing the function for each result, so you can send all your data off to an API or an LLM, and have the ability parse and process everything at once vs individually.
Want to see linting results on just the changes you have made to an OpenAPI document? Or want to see just the results on the differences between two documents? comes with a what changed mode. Using the new
--original and --changes-summary global flags, you can filter out all the noise.
vacuum now supports JSON Path Plus annotations. This means that vacuum is compliant with All Spectral Paths. One of the last remaining gaps between vacuum and spectral has been closed.
Got some rules that don't really need a human to look at?
Well now you can define an
AutoFixFunction for your rules, and when you run with the --fix flag, the fixes will be applied to the file, or use --fix-file to write them to a different file.
Got an error in your spec you know about but can't get round to fixing yet? Migrating from zally and wanting to keep your existing
x-zally-ignore issues silenced?
Now you can! Just add
x-lint-ignore: rule-id to the yaml node reporting the failure (or x-lint-ignore: [rule-one, rule-two] if there are multiple issues to ignore).
---
v0.18: New dashboard, new lint command, new rules!.
Upgrades all around. There is a completely new
dashboard command with a completely new dashboard terminal UI. It's completely interactive and allows you to explore, and filter violations, view full docs and see code. The dashboard command also adds a new -w / --watch flag that will watch your OpenAPI file for changes and re-lint and re-render results automatically.
A re-written
lint command that has a whole new rendering engine and output. Everything is much more readable, easier to see on a screen, matches the new dashboard style. It's 100% backwards compatible with previous versions, all flags as they were.
GET and DELETE operations do not have request bodies. - duplicate-paths - Ensures there are no duplicate paths exist - no-unnecessary-combinator - Ensures no allOf, oneOf or anyOf combinators exist with a single schema inside them. - camel-case-properties - Ensures all schema properties are camelCase.
> 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.
$3
vacuum comes with an interactive dashboard (
vacuum dashboard ) 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.
.pre-commit-config.yaml:`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.
Build an interactive HTML report
` ./vacuum html-report `
You can replace
report-name.html with your own choice of filename. Open the report in your favorite browser and explore the results.
The report file name is _optional_. The default report output name is
vacuum-spectral-report.json
Generate a
vacuum report
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 `
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.
You can ignore specific linting errors by providing an
--ignore-file argument to the lint and report commands.` ./vacuum lint --ignore-file -d `` ./vacuum report --ignore-file -c `
The ignore-file should point to a .yaml file that contains a list of errors to be ignored by vacuum. The structure of the yaml file is as follows:
` : - - : - - ... `
Ignoring errors is useful for when you want to implement new rules to existing production APIs. In some cases, correcting the lint errors would result in a breaking change. Having a way to ignore these errors allows you to implement the new rules for new APIs while maintaining backwards compatibility for existing ones.
---
Try out the dashboard
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 `
---
Supply your own Spectral compatible ruleset
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.
You can configure vacuum using a configuration file named vacuum.conf.yaml
By default, vacuum searches for this file in the following directories 1. Working directory 2.
$XDG_CONFIG_HOME 3. ${HOME}/.config
You can also specify a path to a file using the
--config flag
Global flags are configured as top level nodes
`yaml time: true base: 'http://example.com' ... ` Command specific flags are configured under a node with the commands name `yaml ... lint: silent: true ... `
$3
You can configure global vacuum flags using environmental variables in the form of:
VACUUM_
If a flag, has a
- in it, replace with _
Auto-fixing rule violations
If you have a rule that doesn't need a human to look at it, and the change can be reliably automated you can configure an
AutoFixFunction on the rule. When you then run the lint command you can pass the --fix flag and the violation will be automatically fixed.
for i := 0; i < len(node.Content); i += 2 { if i+1 >= len(node.Content) { break }
keyNode := node.Content[i]
if keyNode.Value == "enum" { keyNode.Value = "x-extensible-enum"
return node, nil } }
return node, nil }
`
> [!NOTE] > The auto fix function must satisfy the
AutoFixFunction type. > It should take in the yaml.Node of the violation, the root yaml.Node of the document and the RuleFunctionContext. > It should return the fixed *yaml.Node and an error.
3. Configure your
RuleSetExecution to use the auto fix function. `go func Lint(rulesFile string, specFile string) error { rules, err := rulesets.LoadLocalRuleSet(ctx, rulesFile) if err != nil { return fmt.Errorf("error loading ruleset: %w", err) }
// NOTE: only showing the fields on the RuleSetExecution relevant to auto-fixing. results := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{ AutoFixFunctions: map[string]model.AutoFixFunction{ "useExtensibleEnum": useExtensibleEnum, }, ApplyAutoFixes: true, RuleSet: rs, })
// Write back to file if fixes were applied if len(lintResults.FixedResults) > 0 && autoFix { fileInfo, _ := os.Stat(specFile)
When the auto fix function runs, if it returns an error the fix will not be applied, the error will be logged, and the violation will be reported in the standard results.
If the auto fix function succeeds the yaml node flagged by the violation will be replaced with the transformed version returned by the auto fix function.
> [!TIP] > When using
vacuum as a library You can access the fixed yaml content in the RuleSetExecutionResult.ModifiedSpec, and choose where to write the file. > > When using vacuum as a cli, the --fix flag will overwrite the spec file in place, and --fix-file` flag lets you specify an alternative file to write the content to, if you want to compare the outputs.
$3
> Logo gopher is modified, originally from egonelbre
