73 lines
1.8 KiB
Markdown
73 lines
1.8 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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
|
|
|
|
```swift
|
|
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.
|
|
|
|
```bash
|
|
swift test
|
|
```
|