{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"bundle","__idx":0},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction","__idx":1},"children":["Introduction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},"."," ","However, most OpenAPI tools don't support that multi-file approach, and require a single-file API description."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly CLI can help you combine separate API description files (such as if you used the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/commands/split"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["split"]}]}," command) into one."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command pulls the relevant parts of an API description into a single file output in JSON or YAML format."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command differs from the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/commands/join"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["join"]}]}," command."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command takes a root OpenAPI file as input and follows the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["join"]}," command can combine multiple OpenAPI files into a single unified API description file."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command first executes preprocessors, then rules, then decorators."," ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#apply-overlays"},"children":["Overlays"]}," are applied after the API description is bundled and before the decorators."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"usage","__idx":2},"children":["Usage"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle <apis>...\nredocly bundle <apis> [--remove-unused-components]\nredocly bundle <apis> [--config=<path>]\nredocly bundle <api> [--overlay=<path>]...\nredocly bundle <apis>... -o <outputName> --ext <ext>\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":3},"children":["Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["apis"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[string]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List of API description root filenames or names assigned in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis"]}," section of your Redocly configuration file. Default values are names defined in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis"]}," section of your configuration file."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--config"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify the path to the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#use-alternative-configuration-file"},"children":["configuration file"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--dereferenced, -d"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Generate fully dereferenced bundle."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--ext"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify the bundled file's extension. The possible values are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["json"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["yaml"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["yml"]},". The default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["yaml"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--extends"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[string]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Can be used in combination with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--lint"]}," to ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/commands/lint#extend-configuration"},"children":["extend a specific configuration"]},". The default values are taken from the Redocly configuration file."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--force, -f"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Generate a bundle output even when errors occur."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--help"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show help."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--keep-url-references, -k"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Preserve absolute URL references."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--lint-config"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify the severity level for the configuration file. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Possible values:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["off"]},". The default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--component-renaming-conflicts-severity"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify the severity level for reporting when schemas are referenced with the same name but different content during bundling. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Possible values:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["off"]},". The default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--metafile"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Path for the bundle metadata file."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--overlay"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[string]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Apply an ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#apply-overlays"},"children":["Overlay"]}," to the bundle. Repeat the option to apply several overlays in order. Replaces the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["overlays"]}," set for the API in the configuration file."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--output, -o"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Name or folder for the bundle file specified using the command line. If you don't specify the file extension, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".yaml"]}," is used by default. If the specified folder doesn't exist, it's created automatically. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Overwrites existing bundler output file."]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--remove-unused-components"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Remove unused components from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," output."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--skip-decorator"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[string]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ignore certain decorators. See the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#skip-preprocessor-rule-or-decorator"},"children":["Skip preprocessor, rule, or decorator section"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--skip-preprocessor"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[string]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ignore certain preprocessors. See the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#skip-preprocessor-rule-or-decorator"},"children":["Skip preprocessor, rule, or decorator section"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--component-names-strategy"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["How to name inlined Schema components. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Possible values:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["basename"]}," (default) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]},". See ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#configure-the-component-names-strategy"},"children":["Configure the component names strategy"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":4},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"bundle-a-single-api-description","__idx":5},"children":["Bundle a single API description"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This command creates a bundled file at the path ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dist/openapi.json"]}," starting from the root API description file ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi/openapi.yaml"]}," and following the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," to other files if appropriate. The bundled file is in JSON format."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle openapi/openapi.yaml --output dist/openapi.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"bundle-multiple-api-descriptions","__idx":6},"children":["Bundle multiple API descriptions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This command creates one bundled file for each of the specified apis in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dist/"]}," folder. Bundled files are in JSON format."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle --output dist --ext json openapi/openapi.yaml openapi/museum.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dist/"]}," folder contents after the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command is executed:"]},{"$$mdtype":"Tag","name":"pre","attributes":{},"children":["\ndist/openapi.json\ndist/museum.json\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alternatively, you can specify the default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["output"]}," location for a bundled API in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis"]}," section of your Redocly configuration file."," ","This is especially useful when bundling multiple APIs."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"apis:\n  orders@v1:\n    root: orders/openapi.yaml\n    output: dist/orders.json\n  accounts@v1:\n    root: accounts/openapi.yaml\n    output: dist/accounts.json\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Given the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," configuration file above, the following command bundles the APIs ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["foo"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bar"]}," into the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dist/"]}," folder."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Please note, that providing an API to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command results in the command bundling only the specified API."," ","Additionally, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--output"]}," option is only meaningful when used with APIs specified in the command line."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-fully-dereferenced-bundle","__idx":7},"children":["Create a fully dereferenced bundle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A fully dereferenced bundle does not use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," syntax."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle --dereferenced --output dist --ext json openapi/openapi.yaml openapi/museum.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["JSON output only works when there are no circular references."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"apply-overlays","__idx":8},"children":["Apply overlays"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://spec.openapis.org/overlay/latest.html"},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command applies Overlay 1.0, 1.1, and 1.2 documents to the bundled API description."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle openapi.yaml --overlay=overlays/public.yaml --overlay=overlays/branding.yaml -o dist/public.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To apply overlays every time an API is bundled, list them under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["overlays"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis"]}," section of your Redocly configuration file."," ","Paths are relative to the configuration file."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"apis:\n  public:\n    root: openapi.yaml\n    output: dist/public.yaml\n    overlays:\n      - overlays/public.yaml\n      - overlays/branding.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--overlay"]}," option replaces the overlays listed in the configuration file."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Overlays are applied to the bundled API description before decorators run and before unused components are removed."," ","Write each action's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target"]}," against the output of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-internal: true"]},", and the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/decorators/remove-x-internal"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," in an overlay value that points to a file is relative to the overlay file, or to the overlay's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$self"]}," URI in Overlay 1.2."," ","The command bundles the referenced files like the rest of the API description."," ","A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," that starts with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["#"]},", such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref: '#/components/schemas/Ticket'"]},", points into the API description."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If an action can't be applied, for example because its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target"]}," isn't a valid JSONPath expression, the command reports an error and doesn't create the bundle unless you use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--force"]},"."," ","An action whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target"]}," matches nothing changes nothing and isn't reported."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/guides/apply-overlays"},"children":["Apply overlays"]}," for a step-by-step guide."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-alternative-configuration-file","__idx":9},"children":["Use alternative configuration file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, the CLI tool looks for the Redocly configuration file in the current working directory. Use the optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--config"]}," argument to provide an alternative path to a configuration file."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle --config=./another/directory/config.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"skip-preprocessor-rule-or-decorator","__idx":10},"children":["Skip preprocessor, rule, or decorator"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You may want to skip specific preprocessors, rules, or decorators upon running the command."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Skip preprocessors","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Skip decorators","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle --skip-decorator=generate-code-samples --skip-decorator=remove-internal-operations\n","lang":"bash"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Tip"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To learn more about preprocessors, rules, and decorators, refer to the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/custom-plugins"},"children":["custom plugins"]}," page."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configure-component-renaming-conflicts","__idx":11},"children":["Configure component renaming conflicts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Schema"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Schema-2"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can adjust how the CLI handles these naming conflicts with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--component-renaming-conflicts-severity"]}," option:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["off"]},": No warnings or errors are shown."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]}," (default): Shows a warning and renames conflicting components automatically."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},": Treats conflicts as errors; the bundling process fails if a naming conflict is detected."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, to fail the bundle instead of silently renaming conflicting components:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle openapi.yaml -o bundled.yaml --component-renaming-conflicts-severity=error\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configure-the-component-names-strategy","__idx":12},"children":["Configure the component names strategy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the bundler inlines an externally-referenced Schema, it must give the component a name."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--component-names-strategy"]}," option controls how that name is derived."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Consider two files that share the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Order.yaml"]}," basename:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# schemas/models/Order.yaml\ntype: object\ntitle: Order model\n\n# schemas/requests/Order.yaml\ntype: object\ntitle: Order request\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"basename (default)","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Names come from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," — the JSON Pointer fragment, or the file's basename when there's no fragment."," ","Because both files are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Order.yaml"]},", they collide and the duplicate is auto-numbered:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle openapi.yaml -o bundled.yaml --component-names-strategy=basename\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The output uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Order"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Order-2"]},"."," ","The auto-numbered suffix is brittle: an unrelated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," change can renumber it."]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"title","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Names come from each schema's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]},", converted to PascalCase (words are split on spaces, capitalized, and joined), so they don't depend on file paths or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," order:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly bundle openapi.yaml -o bundled.yaml --component-names-strategy=title\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The output uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OrderModel"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OrderRequest"]},"."]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Title sanitization"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The OpenAPI and AsyncAPI specifications allow only ASCII letters (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["a"]},"–",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["z"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["A"]},"–",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Z"]},"), digits, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["."]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_"]}," in a Components Object key."," ","All other characters, including non-ASCII letters such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["é"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["я"]},", are replaced with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-"]}," (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["User & Group"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["User-Group"]},")."," ","Schemas without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}," can't be named using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--component-names-strategy=title"]}," strategy."," ","The bundling process reports an error for such schemas."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To catch name collisions before bundling, set the matching ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["strategy"]}," option on the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/rules/oas/component-name-unique"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["component-name-unique"]}]}," rule."]}]},"frontmatter":{},"tagList":["admonition","html","tab","tabs"],"title":"bundle","lastModified":"2026-10-07T06:18:11.000Z"}