Split & Bundle

Split large specs into modular multi-file structures, or bundle references into a single document.

Splitting

The --split option creates a modular file structure with $ref references:

Terminal

npx openapi-format openapi.json -o ./openapi-split/openapi.yaml --split

Example

Before — single file

openapi: 3.0.3
info:
  title: Pet Store API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
  /pets/{petId}:
    get:
      summary: Get pet by ID
      parameters:
        - $ref: '#/components/parameters/petId'
components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
    Error:
      type: object
  parameters:
    petId:
      name: petId
      in: path
      required: true
      schema:
        type: string

After — modular structure

# openapi.yaml (root)
openapi: 3.0.3
info:
  title: Pet Store API
  version: 1.0.0
paths:
  /pets:
    $ref: './paths/pets.yaml'
  /pets/{petId}:
    $ref: './paths/pets_{petId}.yaml'
components:
  schemas:
    Pet:
      $ref: './components/schemas/Pet.yaml'
    Error:
      $ref: './components/schemas/Error.yaml'
  parameters:
    petId:
      $ref: './components/parameters/petId.yaml'

Resulting File Tree

File tree

./openapi-split/
├── openapi.yaml
├── paths/
│   ├── pets.yaml
│   └── pets_{petId}.yaml
├── components/
│   ├── schemas/
│   │   ├── Pet.yaml
│   │   └── Error.yaml
│   └── parameters/
│       └── petId.yaml

Bundling

By default, all $ref references are resolved into a single file. Use --no-bundle to keep references intact:

Terminal

# Default: bundle all $ref into one file
npx openapi-format openapi.json -o bundled.json

# Keep $ref references as-is
npx openapi-format openapi.json -o output.json --no-bundle

Example: Bundling

Before — multi-file with $ref

# openapi.yaml
openapi: 3.0.3
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: './schemas/Pet.yaml'
# schemas/Pet.yaml (separate file)
# type: object
# properties:
#   name:
#     type: string

After — single self-contained file

openapi: 3.0.3
info:
  title: API
  version: 1.0.0
paths:
  /pets:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string