Last updated

bundle

Introduction

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

Usage

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

Options

OptionTypeDescription
apis[string]List of API description root filenames or names assigned in the apis section of your Redocly configuration file. Default values are names defined in the apis section of your configuration file.
--configstringSpecify the path to the configuration file.
--dereferenced, -dbooleanGenerate fully dereferenced bundle.
--extstringSpecify the bundled file's extension. The possible values are json, yaml, or yml. Default value is yaml.
--extends[string]Can be used in combination with --lint to extend a specific configuration. The default values are taken from the Redocly configuration file.
--force, -fbooleanGenerate a bundle output even when errors occur.
--helpbooleanShow help.
--keep-url-references, -kbooleanPreserve absolute URL references.
--lint-configstringSpecify the severity level for the configuration file.
Possible values: warn, error, off. Default value is warn.
--metafilestringPath for the bundle metadata file.
--output, -ostringName or folder for the bundle file. If you don't specify the file extension, .yaml is used by default. If the specified folder doesn't exist, it's created automatically. Overwrites existing bundler output file.
--remove-unused-componentsbooleanRemove unused components from the bundle output.
--skip-decorator[string]Ignore certain decorators. See the Skip preprocessor, rule, or decorator section.
--skip-preprocessor[string]Ignore certain preprocessors. See the Skip preprocessor, rule, or decorator section.
--versionbooleanShow version number.

Examples

Bundle a single API description

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

Bundle multiple API descriptions

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

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.

Create a fully dereferenced bundle

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
Note

JSON output only works when there are no circular references.

Use alternative configuration file

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

Skip preprocessor, rule, or decorator

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
Tip

To learn more about preprocessors, rules, and decorators, refer to the custom plugins page.