YAMLMerger

Swift utility for assembling folder-organized YAML fragments into one OpenAPI specification.

YAMLMerger is useful when a large OpenAPI document is easier to maintain as small files grouped by section, but the build or generator still needs one combined openapi.yaml.

Directory Model

Files are merged in a predictable order:

1. Subfolders are processed alphabetically. Prefix folders with numbers when order matters.
2. YAML files inside each folder are processed alphabetically.
3. Header files such as __paths.yaml sort before ordinary files and can define the parent key for the section.

Example:

Schema/
├── 01_Info/
│   ├── __info.yaml
│   └── api-info.yaml
├── 02_Servers/
│   ├── __servers.yaml
│   └── production.yaml
├── 04_Paths/
│   ├── __paths.yaml
│   ├── users.yaml
│   └── products.yaml
└── 06_Components/
    ├── __components.yaml
    ├── User.yaml
    └── Product.yaml

Usage

import YAMLMerger

let merger = YAMLMerger(
    rootDirectory: URL(fileURLWithPath: "Schema"),
    outputFileName: "openapi.yaml"
)

merger.merge()

The merged file is written inside rootDirectory.

Why This Exists

OpenAPI specs tend to outgrow a single file. Splitting by paths, schemas, and metadata makes review and collaboration easier, while merging keeps the output compatible with tools that expect one document.

YAMLMerger is intentionally simple: it concatenates already-shaped YAML fragments in deterministic order. It does not validate OpenAPI semantics and it does not try to be a general YAML parser.

Testing

The test fixture under Tests/YAMLMergerTests/Schema/ demonstrates the folder layout and merge order.

swift test