split

The split command takes an API description file and creates a 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.

The parts that get split depend on the type of API description:

OpenAPI 3.x

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 openapi-starter tool.

• paths/ - each path item is written to a separate file
• webhooks/ - each webhook is written to a separate file (OpenAPI 3.1+)
• components/ - schemas, responses, parameters, examples, headers, requestBodies, links, callbacks, and securitySchemes are each split into subdirectories

AsyncAPI 2.x

Channels and components are split from the root API description into separate files and folders.

• channels/ - each channel is written to a separate file
• components/ - schemas, messages, securitySchemes, parameters, correlationIds, messageTraits, operationTraits, serverBindings, channelBindings, operationBindings, and messageBindings are each split into subdirectories

AsyncAPI 3.x

Channels, operations, and components are split from the root API description into separate files and folders.

• channels/ - each channel is written to a separate file
• operations/ - each operation is written to a separate file
• components/ - schemas, messages, securitySchemes, servers, serverVariables, parameters, replies, replyAddresses, correlationIds, messageTraits, operationTraits, tags, externalDocs, serverBindings, channelBindings, operationBindings, and messageBindings are each split into subdirectories

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 -n suffix, where n is its order, for example user-2.yaml next to 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 / is replaced with the separator. Code samples in one language for the same operation are saved the same way.

Use the 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 split and bundle allow you to manage your files easily for development, and then prepare a single file for other tools to consume.

redocly split <api> --outDir=<path>
redocly split [--help]

This split command "unbundles" the specified API description, as defined in pet.yaml, into the openapi output directory:

redocly split pet.yaml --outDir=openapi

A confirmation message is displayed with a successful split:

Document: pet.yaml is successfully split
 and all related files are saved to the directory: openapi

pet.yaml: split processed in 33ms

When components, paths, webhooks, channels, or operations have names that differ only by case, such as User and 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 user-2.yaml.

You can adjust how the CLI handles these conflicts with the --file-name-conflicts-severity option:

• off: Saves the later files with a numbered suffix without a warning.
• warn (default): Shows a warning and saves the later files with a numbered suffix.
• error: Treats conflicts as errors; the split fails and no files are created.

For example, to fail the split instead of saving files with a suffix:

redocly split openapi.yaml --outDir=openapi --file-name-conflicts-severity=error