Polish README
This commit is contained in:
parent
4c89a4e550
commit
1f5c36988f
376
README.md
376
README.md
@ -1,327 +1,40 @@
|
||||
# YAMLMerger
|
||||
|
||||
A Swift package for merging multiple YAML files from subdirectories into a single combined file.
|
||||
Swift utility for assembling folder-organized YAML fragments into one OpenAPI
|
||||
specification.
|
||||
|
||||
## How It Works
|
||||
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`.
|
||||
|
||||
YAMLMerger recursively scans subdirectories for YAML files and merges them in a predictable order:
|
||||
## Directory Model
|
||||
|
||||
1. Folders are processed in numerical order (01 → 02 → 03 → ...)
|
||||
2. Within each folder, `__*.yaml` files are merged first (due to `__` prefix)
|
||||
3. All additional YAML files are then merged in alphabetical order
|
||||
4. The result is a single, properly structured OpenAPI specification file
|
||||
Files are merged in a predictable order:
|
||||
|
||||
## Directory Structure for OpenAPI Schemas
|
||||
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.
|
||||
|
||||
When using YAMLMerger for OpenAPI specifications, organize your YAML files into the following subdirectories:
|
||||
Example:
|
||||
|
||||
```
|
||||
```text
|
||||
Schema/
|
||||
├── 01_Info/ # OpenAPI info section (version, title, description, etc.)
|
||||
├── 02_Servers/ # API server URLs and environment configurations
|
||||
├── 03_Tags/ # Tag definitions for organizing endpoints
|
||||
├── 04_Paths/ # API endpoint definitions
|
||||
├── 05_Webhooks/ # Webhook/callback definitions (OpenAPI 3.1+)
|
||||
├── 06_Components/ # Reusable components (schemas, responses, parameters, etc.)
|
||||
├── 07_Security/ # Top-level security requirements
|
||||
└── 08_ExternalDocs/ # External documentation references
|
||||
```
|
||||
|
||||
Place your distinct YAML files into the corresponding folders:
|
||||
|
||||
#### 01_Info/
|
||||
OpenAPI metadata and general information.
|
||||
|
||||
```yaml
|
||||
# __info.yaml (header file)
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
|
||||
# api-info.yaml
|
||||
title: OpenAPI Generation Demo
|
||||
version: 1.0.0
|
||||
description: Demonstration of OpenAPI specification generation using YAMLMerger
|
||||
```
|
||||
|
||||
#### 02_Servers/
|
||||
API server URLs and configurations.
|
||||
|
||||
```yaml
|
||||
# dummyjson-server.yaml
|
||||
- url: https://dummyjson.com
|
||||
description: DummyJSON API Server
|
||||
|
||||
# local-server.yaml
|
||||
- url: http://localhost:8080
|
||||
description: Local development server
|
||||
```
|
||||
|
||||
#### 03_Tags/
|
||||
Tag definitions for organizing endpoints.
|
||||
|
||||
```yaml
|
||||
# tags.yaml
|
||||
- name: auth
|
||||
description: Authentication operations
|
||||
- name: users
|
||||
description: User management operations
|
||||
- name: posts
|
||||
description: Post management operations
|
||||
- name: products
|
||||
description: Product catalog operations
|
||||
```
|
||||
|
||||
#### 04_Paths/
|
||||
API endpoint definitions (one file per resource).
|
||||
|
||||
```yaml
|
||||
# auth.yaml
|
||||
/auth/login:
|
||||
post:
|
||||
operationId: loginUser
|
||||
tags: [auth]
|
||||
summary: User login
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LoginRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: Successful authentication
|
||||
|
||||
# users.yaml
|
||||
/users:
|
||||
get:
|
||||
operationId: getAllUsers
|
||||
tags: [users]
|
||||
summary: Get all users
|
||||
parameters:
|
||||
- name: limit
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
default: 30
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
post:
|
||||
operationId: createUser
|
||||
tags: [users]
|
||||
summary: Add a new user
|
||||
security:
|
||||
- bearerAuth: []
|
||||
responses:
|
||||
'201':
|
||||
description: User created successfully
|
||||
```
|
||||
|
||||
**Try it:**
|
||||
```bash
|
||||
# Auth - Login
|
||||
curl -X POST https://dummyjson.com/auth/login \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"username": "emilys", "password": "emilyspass"}'
|
||||
|
||||
# Users - Get all
|
||||
curl https://dummyjson.com/users?limit=5
|
||||
|
||||
# Users - Get single
|
||||
curl https://dummyjson.com/users/1
|
||||
|
||||
# Posts - Get all
|
||||
curl https://dummyjson.com/posts?limit=5
|
||||
|
||||
# Posts - Get single
|
||||
curl https://dummyjson.com/posts/1
|
||||
|
||||
# Products - Get all
|
||||
curl https://dummyjson.com/products?limit=5
|
||||
|
||||
# Products - Get single
|
||||
curl https://dummyjson.com/products/1
|
||||
|
||||
# Carts - Get all
|
||||
curl https://dummyjson.com/carts?limit=5
|
||||
|
||||
# Carts - Get single
|
||||
curl https://dummyjson.com/carts/1
|
||||
|
||||
# Todos - Get all
|
||||
curl https://dummyjson.com/todos?limit=5
|
||||
|
||||
# Todos - Get single
|
||||
curl https://dummyjson.com/todos/1
|
||||
|
||||
# Comments - Get all
|
||||
curl https://dummyjson.com/comments?limit=5
|
||||
|
||||
# Comments - Get single
|
||||
curl https://dummyjson.com/comments/1
|
||||
```
|
||||
|
||||
#### 05_Webhooks/
|
||||
Webhook/callback definitions (OpenAPI 3.1+).
|
||||
|
||||
```yaml
|
||||
# new-comment.yaml
|
||||
newComment:
|
||||
post:
|
||||
operationId: onNewComment
|
||||
summary: New comment notification
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
event:
|
||||
type: string
|
||||
example: comment.created
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
data:
|
||||
$ref: '#/components/schemas/Comment'
|
||||
|
||||
# new-post.yaml
|
||||
newPost:
|
||||
post:
|
||||
operationId: onNewPost
|
||||
summary: New post notification
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
event:
|
||||
type: string
|
||||
example: post.published
|
||||
data:
|
||||
$ref: '#/components/schemas/Post'
|
||||
```
|
||||
|
||||
**Test webhook receiver:**
|
||||
```bash
|
||||
# Start a local webhook receiver (requires nc)
|
||||
nc -l 8080
|
||||
|
||||
# In another terminal, simulate a webhook POST
|
||||
curl -X POST http://localhost:8080/webhook \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"event": "comment.created",
|
||||
"timestamp": "2025-10-15T10:30:00Z",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"body": "Great post!",
|
||||
"postId": 1,
|
||||
"likes": 5,
|
||||
"user": {
|
||||
"id": 1,
|
||||
"username": "emilys",
|
||||
"fullName": "Emily Johnson"
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
#### 06_Components/
|
||||
Reusable schema definitions (one per file).
|
||||
|
||||
```yaml
|
||||
# LoginRequest.yaml
|
||||
LoginRequest:
|
||||
type: object
|
||||
required: [username, password]
|
||||
properties:
|
||||
username:
|
||||
type: string
|
||||
password:
|
||||
type: string
|
||||
format: password
|
||||
|
||||
# User.yaml
|
||||
User:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
firstName:
|
||||
type: string
|
||||
lastName:
|
||||
type: string
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
|
||||
# Post.yaml
|
||||
Post:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
title:
|
||||
type: string
|
||||
body:
|
||||
type: string
|
||||
userId:
|
||||
type: integer
|
||||
```
|
||||
|
||||
|
||||
#### 07_Security/
|
||||
Security schemes and requirements.
|
||||
|
||||
```yaml
|
||||
# bearer-auth.yaml
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: JWT token obtained from /auth/login endpoint
|
||||
```
|
||||
|
||||
**Try it:**
|
||||
```bash
|
||||
# Get token
|
||||
TOKEN=$(curl -s -X POST https://dummyjson.com/auth/login \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"username": "emilys", "password": "emilyspass"}' \
|
||||
| grep -o '"accessToken":"[^"]*"' | cut -d'"' -f4)
|
||||
|
||||
# Use token to get authenticated user
|
||||
curl https://dummyjson.com/auth/me \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
#### 08_ExternalDocs/
|
||||
Links to external documentation.
|
||||
|
||||
```yaml
|
||||
# __externalDocs.yaml
|
||||
externalDocs:
|
||||
|
||||
# docs.yaml
|
||||
description: DummyJSON Documentation
|
||||
url: https://dummyjson.com/docs
|
||||
```
|
||||
|
||||
The `externalDocs` field provides links to additional documentation outside the API spec. It can be used at:
|
||||
- **Global level** (as shown above) - links to overall API documentation
|
||||
- **Operation level** - links to specific endpoint guides
|
||||
|
||||
Tools like Swagger UI render these links prominently for easy access to tutorials, guides, and examples.
|
||||
|
||||
**Try it:**
|
||||
```bash
|
||||
# View the external documentation
|
||||
curl https://dummyjson.com/docs
|
||||
|
||||
# Or open in browser
|
||||
open https://dummyjson.com/docs
|
||||
├── 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
|
||||
@ -330,29 +43,30 @@ open https://dummyjson.com/docs
|
||||
import YAMLMerger
|
||||
|
||||
let merger = YAMLMerger(
|
||||
rootDirectory: URL(fileURLWithPath: "/path/to/yaml/files"),
|
||||
outputFileName: "CombinedSpec.yaml"
|
||||
rootDirectory: URL(fileURLWithPath: "Schema"),
|
||||
outputFileName: "openapi.yaml"
|
||||
)
|
||||
|
||||
merger.merge()
|
||||
```
|
||||
|
||||
## Requirements
|
||||
The merged file is written inside `rootDirectory`.
|
||||
|
||||
- Swift 6.1+
|
||||
- macOS 14.0+ / iOS 17.0+
|
||||
## Why This Exists
|
||||
|
||||
## Installation
|
||||
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.
|
||||
|
||||
### Swift Package Manager
|
||||
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.
|
||||
|
||||
Add this package as a dependency in your `Package.swift`:
|
||||
## Testing
|
||||
|
||||
```swift
|
||||
dependencies: [
|
||||
.package(url: "https://github.com/yourusername/YAMLMerger", from: "1.0.0")
|
||||
]
|
||||
The test fixture under `Tests/YAMLMergerTests/Schema/` demonstrates the folder
|
||||
layout and merge order.
|
||||
|
||||
```bash
|
||||
swift test
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Add your license here.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user