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.
Tip
To learn more about preprocessors, rules, and decorators, refer to the custom plugins page.
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
Option | Type | Description |
---|---|---|
apis | [string] | List of API root definition filenames or names assigned in the apis section of your Redocly configuration file. Default values are all names defined in the apis section within your configuration file. |
--config | string | Specify path to the config file. |
--dereferenced, -d | boolean | Generate fully dereferenced bundle. |
--ext | string | Specify bundled file extension. 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. Default values are taken from the Redocly configuration file. |
--force, -f | boolean | Generate bundle output even when errors occur. |
--format | string | Format for the output. Possible values are codeframe , stylish , json , or checkstyle . Default value is codeframe . |
--help | boolean | Show help. |
--keep-url-references, -k | boolean | Keep absolute url references. |
--lint | boolean | Lint definition files. Default value is false . |
--max-problems | integer | Truncate output to display the specified maximum number of problems. Default value is 100 . |
--metafile | string | Path for the bundle metadata file. |
--output, -o | string | Name 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. If the file specified as the bundler's output already exists, it's overwritten. |
--remove-unused-components | boolean | Remove 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. |
--skip-rule | [string] | Ignore certain rules. See the Skip preprocessor, rule, or decorator section. |
--version | boolean | Show version number. |
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
Note
JSON output only works when there are no circular references.
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
Tip
To learn more about preprocessors, rules, and decorators, refer to the custom plugins page.