Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/daveshanley/vacuum
vacuum is the worlds fastest OpenAPI 3, OpenAPI 2 / Swagger linter and quality analysis tool. Built in go, it tears through API specs faster than you can think. vacuum is compatible with Spectral rulesets and generates compatible reports.
https://github.com/daveshanley/vacuum
go golang lint linter linters linting oas openapi openapi-spec openapi-specification openapi3 openapi3-1 openapi3-validation openapi31 owasp spectral stoplight swagger swagger-spec swagger-specification
Last synced: 8 days ago
JSON representation
vacuum is the worlds fastest OpenAPI 3, OpenAPI 2 / Swagger linter and quality analysis tool. Built in go, it tears through API specs faster than you can think. vacuum is compatible with Spectral rulesets and generates compatible reports.
- Host: GitHub
- URL: https://github.com/daveshanley/vacuum
- Owner: daveshanley
- License: mit
- Created: 2021-10-10T18:24:19.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-24T16:58:01.000Z (15 days ago)
- Last Synced: 2024-10-29T15:22:27.138Z (10 days ago)
- Topics: go, golang, lint, linter, linters, linting, oas, openapi, openapi-spec, openapi-specification, openapi3, openapi3-1, openapi3-validation, openapi31, owasp, spectral, stoplight, swagger, swagger-spec, swagger-specification
- Language: Go
- Homepage: https://quobix.com/vacuum
- Size: 25 MB
- Stars: 603
- Watchers: 9
- Forks: 50
- Open Issues: 57
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# vacuum - The world's fastest OpenAPI & Swagger linter.
[](https://goreportcard.com/report/github.com/daveshanley/vacuum)
[](https://discord.gg/UAcUF78MQN)
[](https:/-/pkg.go.dev/github.com/daveshanley/vacuum)
[](https://github.com/daveshanley/vacuum/releases)
[](https://www.npmjs.com/package/@quobix/vacuum)
[](https://hub.docker.com/r/dshanley/vacuum)
[](https://github.com/avelino/awesome-go)
An **ultra-super-fast**, lightweight OpenAPI linter and quality checking tool, written in golang and inspired by [Spectral](https://github.com/stoplightio/spectral).
It's also compatible with existing [Spectral](https://github.com/stoplightio/spectral) rulesets.
## Install using [homebrew](https://brew.sh) tap
```
brew install daveshanley/vacuum/vacuum
```
## Install using [npm](https://npmjs.com)
```
npm i -g @quobix/vacuum
```
## Install using [yarn](https://yarnpkg.com/)
```
yarn global add @quobix/vacuum
```
## Install using curl
```
curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
```
## Install using [Docker](https://hub.docker.com/r/dshanley/vacuum)
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
```
Alternatively, you can pull it from
[Github packages](https://github.com/daveshanley/vacuum/pkgs/container/vacuum).
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](https://github.com/sponsors/daveshanley),
like our _very kind_ sponsors:
[Speakeasy](https://speakeasyapi.dev/?utm_source=vacuum+repo&utm_medium=github+sponsorship)
[scalar](https://scalar.com)
---
## Come chat with us
Need help? Have a question? Want to share your work? [Join our discord](https://discord.gg/UAcUF78MQN) and
come say hi!
## Documentation
🔥 **New in** `v0.14+` 🔥 : **Engine Speedup**.
**Speed!** We've made some significant improvements to how efficiently large documents are walked
Which means vacuum is now faster than ever.
---
`v0.12+` : Core functions support JSON Path.
Now all **core** functions return the **correct and accurate JSON path for each linting result**. Previously this was not possible
at all, but with some clever engineering, we have made it happen. It's a small thing, but with huge impact.
This feature has been available on the OpenAPI functions for some time, however core functions were without a comparison.
But no more! core functions have joined the party.
A new `--no-clip` flag is available on the `lint` command. This prevents message/path truncation.
---
`v0.11+`: Ignore Linting Errors/Violations.
v0.11 introduces the ability to ignore specific linting errors. This 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.
[Learn more about ignoring violations](https://quobix.com/vacuum/ignoring/)
---
`v0.10+` : **Quality release**.
v0.10 is a quality release, with a number of fixes and improvements to rule schemas, function names and more.
vacuum now powers [The OpenAPI doctor](https://pb33f.io/doctor/). To enable correct ruleset management and automation
a number of functions have been renamed, interfaces have been upgraded and rule functions schemas are now accurate.
This is a breaking change for anyone using vacuum as a library with custom rules.
---
`v0.9+` : **Built in Language Server**.
A new command is available `language-server`. This starts vacuum as an LSP compatible language server. Run vacuum
in your favorite IDE and get linting and validation as you type, in realtime.
Will support any LSP compatible editor, like VSCode, Sublime, vim, etc.
[Install the VSCode extension](https://marketplace.visualstudio.com/items?itemName=pb33f.vacuum)
[Learn more about the language-server command](https://quobix.com/vacuum/commands/language-server/)
---
`v0.8+` : **OpenAPI Bundler**.
A new command is available `bundle` will bundle all external references for an OpenAPI file into a single file.
[Learn more about the bundle command](https://quobix.com/vacuum/commands/bundle/)
A new linting rule is available `oas-schema-check` will perform type checks and validation on all schemas in your
OpenAPI file. It's enabled by default in the recommended ruleset.
[oas-schema-check rule docs](https://quobix.com/vacuum/rules/schemas/oas-schema-check/)
---
`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](https://quobix.com/vacuum/rulesets/sharing/)
---
`v0.5+` : **Multi-file linting** now available for the `lint` command.
Want to lint multiple files at once? Now you can!
```shell
vacuum lint file1.json path/to/file2.yaml file3.json
```
Want to suck in a ton of files? Use a **glob** pattern!
```shell
vacuum lint some/path/**/*.yaml
```
---
`v0.3+`: [Custom JavaScript Functions](https://quobix.com/vacuum/api/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](https://quobix.com/vacuum/api/custom-javascript-functions/).
---
`v0.2+`: [OWASP API rules](https://quobix.com/vacuum/rules/owasp/) are now available out of the box.
[Learn more about enabling OWASP API rules](https://quobix.com/vacuum/rulesets/owasp/).
---
### [Quick Start Guide 🚀](https://quobix.com/vacuum/start)
See all the documentation at https://quobix.com/vacuum
- [Installing vacuum](https://quobix.com/vacuum/installing/)
- [About vacuum](https://quobix.com/vacuum/about/)
- [Why should you care?](https://quobix.com/vacuum/why/)
- [Concepts](https://quobix.com/vacuum/concepts/)
- [FAQ](https://quobix.com/vacuum/faq/)
- [CLI Commands](https://quobix.com/vacuum/commands/)
- [lint](https://quobix.com/vacuum/commands/lint/)
- [vacuum report](https://quobix.com/vacuum/commands/report/)
- [dashboard](https://quobix.com/vacuum/commands/dashboard/)
- [html-report](https://quobix.com/vacuum/commands/html-report/)
- [bundle](https://quobix.com/vacuum/commands/bundle/)
- [spectral-report](https://quobix.com/vacuum/commands/spectral-report/)
- [Developer API](https://quobix.com/vacuum/api/getting-started/)
- [Using The Index](https://quobix.com/vacuum/api/spec-index/)
- [RuleResultSet](https://quobix.com/vacuum/api/rule-resultset/)
- [Loading a RuleSet](https://quobix.com/vacuum/api/loading-ruleset/)
- [Linting Non-OpenAPI Files](https://quobix.com/vacuum/api/non-openapi/)
- [Custom Golang Functions](https://quobix.com/vacuum/api/custom-functions/)
- [Custom JavaScript Functions](https://quobix.com/vacuum/api/custom-javascript-functions/)
- [Rules](https://quobix.com/vacuum/rules/)
- [Examples](https://quobix.com/vacuum/rules/examples/)
- [Tags](https://quobix.com/vacuum/rules/tags/)
- [Descriptions](https://quobix.com/vacuum/rules/descriptions/)
- [Schemas](https://quobix.com/vacuum/rules/schemas/)
- [Spec Information](https://quobix.com/vacuum/rules/information/)
- [Operations & Paths](https://quobix.com/vacuum/rules/operations/)
- [Validation](https://quobix.com/vacuum/rules/validation/)
- [Security](https://quobix.com/vacuum/rules/security/)
- [OWASP](https://quobix.com/vacuum/rules/owasp/)
- [Functions](https://quobix.com/vacuum/functions/)
- [Core Functions](https://quobix.com/vacuum/functions/core/)
- [OpenAPI Functions](https://quobix.com/vacuum/functions/openapi/)
- [OWASP Functions](https://quobix.com/vacuum/functions/owasp/)
- [Understanding RuleSets](https://quobix.com/vacuum/rulesets/understanding/)
- [Sharing RuleSets](https://quobix.com/vacuum/rulesets/sharing/)
- [All Rules](https://quobix.com/vacuum/rulesets/all/)
- [No Rules](https://quobix.com/vacuum/rulesets/no-rules/)
- [Recommended Rules](https://quobix.com/vacuum/rulesets/recommended/)
- [Custom Rules](https://quobix.com/vacuum/rulesets/custom-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.
### Dashboard
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.
### HTML Report
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.
## Using vacuum with pre-commit
Vacuum can be used with [pre-commit](https://pre-commit.com).
To do that, add to your `.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](./.pre-commit-hooks.yaml) 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.
## See full linting report
```
./vacuum lint -d
```
## Lint multiple files at once
```
./vacuum lint -d
```
## Lint multiple files using a glob pattern
```
./vacuum lint -d some/path/**/*.yaml
```
## See full linting report with inline code snippets
```
./vacuum lint -d -s
```
## See just the linting errors
```
./vacuum lint -d -e
```
## See just a specific category of report
```
./vacuum lint -d -c schemas
```
The options here are:
- `examples`
- `operations`
- `information`
- `descriptions`
- `schemas`
- `security`
- `tags`
- `validation`
- `owasp`
## Generate a Spectral compatible report
If you're already using Spectral JSON reports, and you want to use vacuum instead, use the `spectral-report` command
```
./vacuum spectral-report
```
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.
> When using compression, the file name will be `vacuum-report-MM-DD-YY-HH_MM_SS.json.gz`. vacuum uses gzip internally.
## Ignoring specific linting errors
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](https://meta.stoplight.io/docs/spectral/e5b9616d6d50c-custom-rulesets#custom-rulesets),
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.
### Here are some examples you can try
**_All rules turned off_**
```
./vacuum lint -r rulesets/examples/norules-ruleset.yaml
```
**_Only recommended rules_**
```
./vacuum lint -r rulesets/examples/recommended-ruleset.yaml
```
**_Enable specific rules only_**
```
./vacuum lint -r rulesets/examples/specific-ruleset.yaml
```
**_Custom rules_**
```
./vacuum lint -r rulesets/examples/custom-ruleset.yaml
```
**_All rules, all of them!**
```
./vacuum lint -r rulesets/examples/all-ruleset.yaml
```
---
## Configuration
### 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
...
```
### Environmental variables
You can configure global vacuum flags using environmental variables in the form of: `VACUUM_`
If a flag, has a `-` in it, replace with `_`
> Logo gopher is modified, originally from [egonelbre](https://github.com/egonelbre/gophers)