bundle

Introduction

API definitions 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 definition by referencing them with $ref. However, most OpenAPI tools don't support that multi-file approach, and require a single-file API definition.

Redocly CLI can help you combine separate API definition files into one. The bundle command pulls the relevant parts of an API definition into a single file output in JSON or YAML format.

The bundle command first executes preprocessors, then rules, then decorators.

Usage

redocly bundle <apis>...
redocly bundle <apis> [--max-problems=<n>]
redocly bundle <apis> [--lint] [--config=<path>]
redocly bundle <apis>... -o <outputName> --ext <ext>
redocly bundle --version

Options

Examples

Bundle a single API definition

This command creates a bundled file at the path dist/openapi.json starting from the root API definition file openapi/openapi.yaml. The bundled file is in JSON format.

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

Bundle multiple API definitions

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/petstore.yaml

dist/openapi.json
dist/petstore.json

Create a fully dereferenced bundle

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

Custom 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

Format

Codeframe (default)

redocly bundle pet.yaml store.yaml -o ./bundled --format=codeframe
## equivalent to: redocly bundle pet.yaml store.yaml -o ./bundled

Note: Errors display in the following format: file:line:column. For example, petstore-with-errors.yaml:16:3.

Depending on the terminal emulator you use, it may be possible to directly click this indicator to edit the file in place.

Stylish

redocly bundle pet.yaml store.yaml -o ./bundled --format=stylish

In this format, bundle shows the filename, line number, and column where the problem occurred.

The compressed output omits other contexts and suggestions.

JSON

redocly bundle pet.yaml store.yaml -o ./bundled --format=json

bundling pet.yaml...
{
  "totals": {
    "errors": 0,
    "warnings": 0,
    "ignored": 0
  },
  "version": "1.0.0-beta.54",
  "problems": []
}📦 Created a bundle for pet.yaml at bundled/pet.yaml 28ms.
bundling store.yaml...
{
  "totals": {
    "errors": 0,
    "warnings": 0,
    "ignored": 0
  },
  "version": "1.0.0-beta.54",
  "problems": []
}📦 Created a bundle for store.yaml at bundled/store.yaml 15ms.

In this format, bundle shows the result of bundling (including the number of errors and warnings and their descriptions) in JSON-like output.

Checkstyle

redocly bundle pet.yaml -o ./bundled --lint --format=checkstyle

bundling pet.yaml...
<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="4.3">
<file name="pet.yaml">
</file>
</checkstyle>
📦 Created a bundle for pet.yaml at bundled/pet.yaml 35ms.

In this format, bundle uses the Checkstyle XML report format. Due to the limitations of this format, the output only includes the filename, line, column, severity, and rule ID (in the source attribute). All other information is omitted.

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,another-example

redocly bundle --skip-rule=no-sibling-refs,no-parent-tags

redocly bundle --skip-decorator=generate-code-samples,remove-internal-operations