Every OpenAPI file is different, but most of them are lengthy. It is common to see files at 10, 30 or even 50 thousand lines long. Working with files this size can be laborious, jumping between sections to edit or to review changes. Redocly CLI makes this easier by offering commands to split the file up and make things more manageable.
OpenAPI is designed with support for
$ref syntax, allowing parts of an API description to be described elsewhere, and reused between multiple descriptions. Redocly CLI takes advantage of this feature and provides the
split to break your specification into multiple files.
If you have one large single file, split it up like this:
redocly split openapi.yaml --outDir myApi
The original file is unchanged, but look in the directory named by the
--outDir parameter. It now contains:
openapi.yamlfile, which is the entry point of the API and includes the
infosection and other metadata. This file also contains the bare bones of the API description, with all the details moved to dedicated files.
paths/directory, with a file for each of the URLs in the API. All verbs for that endpoint are in this file.
components/directory containing subdirectories for each of the top-level keys, such as
schema, and files for the individual data structures described in each section.
By keeping your API in this format, managing changes can be easier since it's clear which file (or files) have changed, making it easier to review as things change. Many common operations can be performed on the API description in this format, such as linting. Some tools prefer a single bundled OpenAPI description, and it's common to bundle during CI (continuous integration) before doing other automated operations.
OpenAPI is designed to work across multiple files, but not all tools (or people) like to work that way. Whether you
split your API description files to make it more manageable, or your API description contains
$refs to common descriptions, the
bundle command turns it back into a single file.
Some tools require one file, so it's likely that you may need this step at some point in your workflow.
Use the bundle command like this:
redocly bundle openapi.yaml -o bundled.yaml
All the references are brought into a single file, that you can then pass on to other tools in your API workflow.
--lint to the bundle command to have Redocly CLI check your API meets the expected standards before bundling. Learn more about API standards and linting
This feature is experimental, and supports OpenAPI 3.x only
When you have multiple APIs but want to publish a single API description file, the
join may meet your needs. This can be useful when you are providing a combined offering and want to create unified documentation, or use a single input to other tools.
Use the command to combine files like this:
redocly join api1.yaml api2.yaml -o apis-combined.yaml
Supply as many API descriptions as you need to; the first one is used for the
info and other metadata, endpoints from the following files are then added to the OpenAPI description.
It's sometimes nice to get an overall view of complex API descriptions. Redocly CLI has a
stats command that gives a simple overview of what's in a file.
redocly stats openapi.yaml
Gives a summary of the API, including the number of operations, tags, schemas, and other measurements.
- See all Redocly CLI commands
- Learn how to filter out internal API endpoints before publishing if you have more detailed API descriptions than you want to pass to another stage of the API workflow