redocly bundle: Flatten a Multi-File OpenAPI
redocly bundle resolves every $ref in a split OpenAPI project and writes one self-contained file.
Many teams author OpenAPI across many files for sanity, but publishing and diffing want a single document. bundle collapses the tree while keeping internal references intact.
What it does
redocly bundle follows external $refs in the root document and inlines them into one file, preserving component references as internal $refs unless you pass --dereferenced. The result validates as a standalone OpenAPI file.
Common usage
redocly bundle openapi.yaml -o dist/openapi.yaml
# fully dereferenced JSON output
redocly bundle openapi.yaml --dereferenced -o dist/openapi.json --ext jsonOptions
| Flag | What it does |
|---|---|
| -o, --output <file> | Output path for the bundled document |
| --ext <yaml|json|yml> | Output file extension/format |
| -d, --dereferenced | Inline all $refs instead of keeping internal ones |
| --remove-unused-components | Drop components not referenced anywhere |
| --config <file> | Path to redocly.yaml |
In CI
Bundle before you publish or before you run a diff tool that expects one file, and commit the bundled artifact (or attach it to the release). Pair redocly bundle with redocly lint so you validate the same document you ship.
Common errors in CI
"Cannot resolve $ref ... ENOENT" means a referenced file path is wrong relative to the file that references it. "Failed to resolve $ref" with a JSON pointer means the fragment (e.g. #/components/schemas/Foo) does not exist in the target. Circular $refs are allowed in output but cannot be fully --dereferenced; drop the flag if bundling hangs or errors on a cycle.