vacuum - The world's fastest OpenAPI & Swagger linter.

An ultra-super-fast, lightweight OpenAPI linter and quality checking tool, written in golang and inspired by Spectral.

It's fully 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

Install using curl

curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh

For CI/CD environments

To avoid GitHub API rate limiting in automated environments, set a GitHub token:

# 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

- 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.

Install using Docker

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 <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.

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 <your-openapi-spec.yaml>

Come chat with us

Need help? Have a question? Want to share your work? Join our discord and come say hi!

Documentation

🔥 New in v0.25 🔥: Generate Open Collections from OpenAPI files

A new open-collection command will generate an Open Collection Workflow folder (or bundled file)

Open Collection is a new standard for defining and sharing API collections. vacuum supports it natively.

v0.24: TURBO MODE

A huge tune up of hundreds of systems across the stack has resulted in significant speed boosts and improved memory performance.

| Spec | Size | v0.23 | Turbo | Speedup | |------|------|-------|-------|-----| | petstore.yaml | 21KB | 0.03s | 0.02s | 33% | | mistral.yaml | 292KB | 0.17s | 0.10s | 41% | | neon.yaml | 370KB | 0.21s | 0.08s | 62% | | ld.yaml | 1.9MB | 0.93s | 0.31s | 67% | | plaid.yml | 2.9MB | 1.39s | 0.53s | 62% | | stripe.yaml | 6.1MB | 3.11s | 0.85s | 73% |

The bigger the spec, the faster vacuum runs!

New -T flag will enable turbo mode. Go ultra-fast!

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 apply-overlay command.

Learn more about the apply-overlay command

v0.22: Async Functions / Promises, Fetch & Batch mode in Custom JS Functions

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.

v0.21: Change detection filtering

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.

documentation for change detection is available to learn more.

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.

See all the newly supported annotations

v0.20: Support for auto fixing custom rules

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.

See Auto-Fixing Rule Violations for more specifics.

v0.19: Ignore rules with x-lint-ignore

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.

New rules:

no-request-body - Ensures 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.

v0.17: Github Action.

vacuum now has an official Github Action. Read the docs, or check it out in the GitHub Marketplace.

v0.16.11: **Composed bundl

Vacuum

Install / Use

README