{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"split","__idx":0},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["split"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction","__idx":1},"children":["Introduction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["split"]}," command takes an API description file and creates a ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/resources/multi-file-definitions/"},"children":["multi-file structure"]}," out of it by extracting referenced parts into standalone, separate files."," ","The advantage of this approach is making smaller files that are easier to manage and a structure that makes reviewing simpler."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Supported specifications"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["split"]}," command supports OpenAPI 3.x, AsyncAPI 2.x, and AsyncAPI 3.x descriptions. OpenAPI 2.x (Swagger) is not supported."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The parts that get split depend on the type of API description:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OpenAPI 3.x"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Components, paths, and webhooks are split from the root API description into separate files and folders."," ","The structure of the unbundled directory corresponds to the structure created by the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/Redocly/openapi-starter"},"children":["openapi-starter"]}," tool."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paths/"]}," - each path item is written to a separate file"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooks/"]}," - each webhook is written to a separate file (OpenAPI 3.1+)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components/"]}," - schemas, responses, parameters, examples, headers, requestBodies, links, callbacks, and securitySchemes are each split into subdirectories"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["AsyncAPI 2.x"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Channels and components are split from the root API description into separate files and folders."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channels/"]}," - each channel is written to a separate file"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components/"]}," - schemas, messages, securitySchemes, parameters, correlationIds, messageTraits, operationTraits, serverBindings, channelBindings, operationBindings, and messageBindings are each split into subdirectories"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["AsyncAPI 3.x"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Channels, operations, and components are split from the root API description into separate files and folders."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channels/"]}," - each channel is written to a separate file"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operations/"]}," - each operation is written to a separate file"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components/"]}," - schemas, messages, securitySchemes, servers, serverVariables, parameters, replies, replyAddresses, correlationIds, messageTraits, operationTraits, tags, externalDocs, serverBindings, channelBindings, operationBindings, and messageBindings are each split into subdirectories"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Components, paths, webhooks, channels, and operations are written to files named after them."," ","When several of them would share one file, each later file gets a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-n"]}," suffix, where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["n"]}," is its order, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user-2.yaml"]}," next to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["User.yaml"]},"."," ","That happens when names differ only by case, which a case-insensitive file system treats as one file name, or when names become equal after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/"]}," is replaced with the separator."," ","Code samples in one language for the same operation are saved the same way."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/commands/bundle"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}]}," command and supply the main file as the entrypoint to get your API description back in one file."," ","Many API tools prefer a single file, but ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["split"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," allow you to manage your files easily for development, and then prepare a single file for other tools to consume."]},{"$$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 split <api> --outDir=<path>\nredocly split [--help]\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":["api"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," Path to the API description file that you want to split into a multi-file structure."]}]},{"$$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":"/docs/cli/v2/configuration"},"children":["configuration file"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--file-name-conflicts-severity"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify the severity level for reporting when two names differ only by case and would share one 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"]},". Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},"."]}]},{"$$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":["--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"]},". Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--outDir"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," Path to the directory where you want to save the split files. If the specified directory doesn't exist, it is created automatically."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--separator"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["File path separator used while splitting. Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_"]},". Controls the file names generated in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paths"]}," folder (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/users/create"]}," path becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_create.yaml"]},", root level path ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_.yaml"]},", and so on)."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":4},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"view-successful-split-message","__idx":5},"children":["View successful split message"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["split"]}," command \"unbundles\" the specified API description, as defined in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pet.yaml"]},", into the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi"]}," output directory:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly split pet.yaml --outDir=openapi\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A confirmation message is displayed with a successful split:"]},{"$$mdtype":"Tag","name":"pre","attributes":{},"children":["\nDocument: pet.yaml is successfully split\n and all related files are saved to the directory: openapi\n\npet.yaml: split processed in 33ms\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configure-file-name-conflicts","__idx":6},"children":["Configure file name conflicts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When components, paths, webhooks, channels, or operations have names that differ only by case, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["User"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]},", they would share one file on a case-insensitive file system."," ","By default, Redocly CLI warns about these conflicts and saves every later one to a file with a numbered suffix, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user-2.yaml"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can adjust how the CLI handles these conflicts with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--file-name-conflicts-severity"]}," option:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["off"]},": Saves the later files with a numbered suffix without a warning."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]}," (default): Shows a warning and saves the later files with a numbered suffix."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},": Treats conflicts as errors; the split fails and no files are created."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, to fail the split instead of saving files with a suffix:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly split openapi.yaml --outDir=openapi --file-name-conflicts-severity=error\n","lang":"bash"},"children":[]}]},"frontmatter":{},"tagList":["admonition","html"],"title":"split","lastModified":"2026-10-07T06:18:11.000Z"}