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 do not support that multi-file approach, and require a single-file API definition.

Redocly OpenAPI 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 rules page.

Usage

Copy
Copied
openapi bundle <entrypoints>...
openapi bundle <entrypoints> [--max-problems=<n>]
openapi bundle <entrypoints> [--lint] [--config=<path>]
openapi bundle <entrypoints>... -o <outputName> --ext <ext>
openapi bundle --version

Options

Option Type Required? Default Description
entrypoints array yes [] Array of API root definition filenames that need to be bundled. Instead of full paths, you can use aliases assigned in the apiDefinitions section within your .redocly.yaml configuration file as entrypoints.
--config string no - Specify path to the config file
--dereferenced, -d boolean no - Generate fully dereferenced bundle
--ext string no yaml Specify bundled file extension.
Possible values: json, yaml, yml
--extends array no - Can be used in combination with --lint to Extend a specific configuration (defaults or config file settings)
--force, -f boolean no - Generate bundle output even when errors occur
--format string no codeframe Format for the output.
Possible values: codeframe, stylish, json
--help boolean no - Show help
--lint boolean no false Lint definition files.
--max-problems number no 100 Truncate output to display the specified maximum number of problems
--metafile string no - Path for the bundle metadata file. For example, --metafile ./bundle.metadata.json
--output, -o string no - Name or folder for the bundle file. For example, -o bundle.yaml or -o ./openapi.
  • If you don't specify the extension, .yaml will be used by default.
  • If the specified folder doesn't exist, it will be created automatically.

  • If the file specified as the bundler's output already exists, it will be overwritten
    --skip-decorator array no - Ignore certain decorators. See the Skip preprocessor, rule, or decorator section below
    --skip-preprocessor array no - Ignore certain preprocessors. See the Skip preprocessor, rule, or decorator section below
    --skip-rule array no - Ignore certain rules. See the Skip preprocessor, rule, or decorator section below
    --version boolean no - 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.

    Copy
    Copied
    openapi bundle openapi/openapi.yaml --output dist/openapi.json

    Bundle multiple API definitions

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

    requestoutput
    Copy
    Copied
    openapi bundle --output dist --ext json openapi/openapi.yaml openapi/petstore.yaml
    Copy
    Copied
    dist/openapi.json
    dist/petstore.json

    Create a fully dereferenced bundle

    Note

    JSON output only works when there are no circular references.

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

    Custom configuration file

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

    Copy
    Copied
    openapi bundle --config=./another/directory/config.yaml

    Format

    Codeframe (default)

    requestoutput
    Copy
    Copied
    openapi bundle pet.yaml store.yaml -o ./bundled --format=codeframe
    ## equivalent to: openapi bundle pet.yaml store.yaml -o ./bundled
    Copy
    Copied
    ...

    Note: Any errors are displayed 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

    requestoutput
    Copy
    Copied
    openapi bundle pet.yaml store.yaml -o ./bundled --format=stylish
    Copy
    Copied
    ...

    In this format, bundle shows the file name, line number, and column where the problem occurred. However, the output is compressed and omits other contexts and suggestions.

    JSON

    requestoutput
    Copy
    Copied
    openapi bundle pet.yaml store.yaml -o ./bundled --format=json
    Copy
    Copied
    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.

    Skip preprocessor, rule, or decorator

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

    Skip preprocessorsSkip rulesSkip decorators
    Copy
    Copied
    openapi bundle --skip-preprocessor=discriminator-mapping-to-one-of,another-example
    Copy
    Copied
    openapi bundle --skip-rule=no-sibling-refs,no-parent-tags
    Copy
    Copied
    openapi bundle --skip-decorator=generate-code-samples,remove-internal-operations
    Tip

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