Lots of OpenAPI specifications are exploded out across lots of different files. This is great for maintainability, but not so great for portability.

Many OpenAPI tools do not support exploded / multi-file OpenAPI specifications.

Loading and locating references can be tricky, particularly when they are spread across local or remote file systems, so lots of tools just give up on trying to locate references and just ask for a single monolithic file.

Local references (references inside the root document) are not bundled, They stay in place.

Bundle an OpenAPI specification

vacuum bundle expanded-openapi.yaml bundled-openapi.yaml

Circular References will be ignored when bundling.

Composed vs inline mode

There are two ways to bundle an exploded spec, the first is to just inline every reference in place. Inlining means no references, which is great for all tools, however, it results in a lot of duplication as well.

This is the default behavior of the bundle command.

The second mode is composed mode, using the --composed or -c flag.

When composing a bundled document, vacuum will extract every reference and move it to the root document as a component in the appropriate components section.

An example of a composed spec which is created from this exploded spec

Handling collisions

When composing a bundle, names of references may conflict with one another. Conflicts happen because the same names are re-used across files, or the same file names are used inside directories.

To handle any conflicts, vacuum will create a unique name for each conflict, using a delimiter as a separator between each word. For example UserAccount__corporate.

The delimiter used can be customized by using the --delimiter or -d flag. The default is __ but it can be any string.

Available Flags

bundle supports the following flags

Short Full Input Description
-c –composed bool Compose exploded spec into a new spec, retaining references - but moving them inline
-d –delimiter string When using --composed any name clashes are spaced with a delimiter (defaults to __)
-q –no-style bool Disable color and style console output (useful for CI/CD)
-i –stdin bool Use stdin instead of reading OpenAPI spec from a file
-o –stdout bool Use stdout instead of writing report to a file
-p –base string Base filepath or URL to external references