This guide helps beginner API writers and developers split and bundle OpenAPI documentation using Redocly CLI. The goal is to organize a single monolithic OpenAPI file into reusable components and then bundle it for publication.

What You’ll Learn

How to split a monolithic OpenAPI file using Redocly CLI
How to configure Redocly CLI for customizations
How to bundle those files into a single OpenAPI spec for publishing
How to lint your OpenAPI spec

Step 1: Sample Monolithic OpenAPI File

Suppose you start with a file: main.yaml

openapi: 3.0.3
info:
  title: Sample API
  version: 1.0.0
  license:
    name: 3.0 License
servers:
  - url: https://www.example.com
paths:
  /users:
    get:
      summary: Get all users
      operationId: GetUsers
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

Step 2: Split the Monolithic File

Use the Redocly CLI split command to modularize the file:

redocly split main.yaml --outDir=./openapi

This will create a structured folder (./openapi) with separate files for paths and components, for example:

openapi/
├── main.yaml
├── paths/
│   └── users.yaml
└── components/
    └── schemas/
        └── user.yaml

Example: openapi/main.yaml after splitting

openapi: 3.0.3
info:
  title: Sample API
  version: 1.0.0
  license:
    name: 3.0 License
servers:
  - url: https://www.example.com
paths:
  $ref: './paths/users.yaml'
components:
  schemas:
    $ref: './components/schemas/user.yaml'

Example: openapi/paths/users.yaml

/users:
  get:
    summary: Get all users
    operationId: GetUsers
    responses:
      '200':
        description: A list of users
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '../components/schemas/user.yaml#/User'

Example: openapi/components/schemas/user.yaml

User:
  type: object
  properties:
    id:
      type: string
    name:
      type: string

Step 3: Add Redocly Config File

Create a redocly.yamlat the root level:

apis:
  main: ./openapi/main.yaml
extends:
  - recommended
rules:
  tag-description: error
  operation-summary: error
  no-unresolved-refs: error
  no-unused-components: error
  operation-2xx-response: error
  operation-operationId: error
  operation-singular-tag: error
  no-enum-type-mismatch: error
  no-identical-paths: error
  no-ambiguous-paths: error

💡

This config file lets you customize linting rules and manage multiple API definitions.

Step 4: Bundle the Modular Files

Use the bundle command to combine the modular files into one OpenAPI file for publishing or sharing:

redocly bundle openapi/main.yaml --output bundled.yaml

This generates a single bundled.yaml file with all references resolved.

Step 5: Lint Your Specs

Use the lint command to validate your OpenAPI definition:

redocly lint openapi/main.yaml

This helps catch unresolved references, missing fields, and other schema violations.

Best Practices

Practice	Description
Modularize logically	Separate schemas, parameters, paths clearly
Use meaningful file names	E.g., `user.yaml`, `error.yaml`, `pagination.yaml`
Keep references relative	Use `./` or `../` instead of absolute paths
Validate early and often	Run `lint` after every major edit
Document folder structure	Add a README for contributors

Troubleshooting Tips

Error: unresolved $ref — Double-check relative paths and file names.
Bundled file missing parts — Ensure all component files are referenced in main.yaml.
YAML syntax errors — Use an online YAML validator or a linter.

Resources

Happy documenting!

Redocly CLI: Splitting & Bundling OpenAPI Specs (Beginner-Friendly Guide)