bundle

API descriptions can grow and become difficult to manage, especially if several teams are collaborating on them. It's a good practice to maintain the reusable parts as separate files, and include them in the main (root) API description by referencing them with $ref. However, most OpenAPI tools don't support that multi-file approach, and require a single-file API description.

Redocly CLI can help you combine separate API description files (such as if you used the split command) into one. The bundle command pulls the relevant parts of an API description into a single file output in JSON or YAML format.

The bundle command differs from the join command. The bundle command takes a root OpenAPI file as input and follows the $ref mentions to include all the referenced components into a single output file. All components are automatically resolved and included without requiring explicit definitions. The join command can combine multiple OpenAPI files into a single unified API description file.

The bundle command first executes preprocessors, then rules, then decorators. Overlays are applied after the API description is bundled and before the decorators.

redocly bundle <apis>...
redocly bundle <apis> [--remove-unused-components]
redocly bundle <apis> [--config=<path>]
redocly bundle <api> [--overlay=<path>]...
redocly bundle <apis>... -o <outputName> --ext <ext>
redocly bundle --version

This command creates a bundled file at the path dist/openapi.json starting from the root API description file openapi/openapi.yaml and following the $ref to other files if appropriate. The bundled file is in JSON format.

redocly bundle openapi/openapi.yaml --output dist/openapi.json

This command creates one bundled file for each of the specified apis in the dist/ folder. Bundled files are in JSON format.

redocly bundle --output dist --ext json openapi/openapi.yaml openapi/museum.yaml

The dist/ folder contents after the bundle command is executed:

dist/openapi.json
dist/museum.json

Alternatively, you can specify the default output location for a bundled API in the apis section of your Redocly configuration file. This is especially useful when bundling multiple APIs.

apis:
  orders@v1:
    root: orders/openapi.yaml
    output: dist/orders.json
  accounts@v1:
    root: accounts/openapi.yaml
    output: dist/accounts.json

Given the redocly.yaml configuration file above, the following command bundles the APIs foo and bar into the dist/ folder.

redocly bundle

Please note, that providing an API to the bundle command results in the command bundling only the specified API. Additionally, the --output option is only meaningful when used with APIs specified in the command line.

A fully dereferenced bundle does not use $ref at all, all the references are resolved and placed into the API description file. This can be useful if you need to prepare an OpenAPI file to be used by another tool that does not understand the $ref syntax.

redocly bundle --dereferenced --output dist --ext json openapi/openapi.yaml openapi/museum.yaml

An Overlay describes changes to an API description in a separate file, for example to hide internal operations or add details for a public version of an API. The bundle command applies Overlay 1.0, 1.1, and 1.2 documents to the bundled API description.

redocly bundle openapi.yaml --overlay=overlays/public.yaml --overlay=overlays/branding.yaml -o dist/public.yaml

To apply overlays every time an API is bundled, list them under overlays in the apis section of your Redocly configuration file. Paths are relative to the configuration file.

apis:
  public:
    root: openapi.yaml
    output: dist/public.yaml
    overlays:
      - overlays/public.yaml
      - overlays/branding.yaml

The --overlay option replaces the overlays listed in the configuration file.

Overlays are applied to the bundled API description before decorators run and before unused components are removed. Write each action's target against the output of redocly bundle without overlays: it reaches everything the bundle includes, even parts that live in separate files. Decorators see the changes the overlays make. For example, an overlay can mark operations with x-internal: true, and the remove-x-internal decorator then removes them. When you create a dereferenced bundle, the overlays are applied before the references are resolved, so a change to a component reaches every place that uses it.

A $ref in an overlay value that points to a file is relative to the overlay file, or to the overlay's $self URI in Overlay 1.2. The command bundles the referenced files like the rest of the API description. A $ref that starts with #, such as $ref: '#/components/schemas/Ticket', points into the API description.

If an action can't be applied, for example because its target isn't a valid JSONPath expression, the command reports an error and doesn't create the bundle unless you use --force. An action whose target matches nothing changes nothing and isn't reported.

See Apply overlays for a step-by-step guide.

By default, the CLI tool looks for the Redocly configuration file in the current working directory. Use the optional --config argument to provide an alternative path to a configuration file.

redocly bundle --config=./another/directory/config.yaml

You may want to skip specific preprocessors, rules, or decorators upon running the command.

redocly bundle --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example

When bundling API descriptions that contain external references, you may encounter situations where different schemas use the same name but have different contents. By default, Redocly CLI warns you about these naming conflicts and automatically renames the duplicates (for example, renaming Schema to Schema-2).

You can adjust how the CLI handles these naming conflicts with the --component-renaming-conflicts-severity option:

• off: No warnings or errors are shown.
• warn (default): Shows a warning and renames conflicting components automatically.
• error: Treats conflicts as errors; the bundling process fails if a naming conflict is detected.

For example, to fail the bundle instead of silently renaming conflicting components:

redocly bundle openapi.yaml -o bundled.yaml --component-renaming-conflicts-severity=error

When the bundler inlines an externally-referenced Schema, it must give the component a name. The --component-names-strategy option controls how that name is derived.

Consider two files that share the Order.yaml basename:

# schemas/models/Order.yaml
type: object
title: Order model

# schemas/requests/Order.yaml
type: object
title: Order request

redocly bundle openapi.yaml -o bundled.yaml --component-names-strategy=basename

To catch name collisions before bundling, set the matching strategy option on the component-name-unique rule.