Quick Start¶

Get started with OAS Patcher in just 5 minutes! This guide will walk you through applying your first overlay to an OpenAPI specification.

What You'll Learn¶

By the end of this guide, you'll know how to:

Apply overlays to OpenAPI documents
Use the CLI effectively
Understand basic overlay structure

Step 1: Prepare Sample Files¶

Let's start with a simple OpenAPI specification and an overlay.

Create `petstore.yaml`¶

Create a basic OpenAPI specification:

openapi: 3.0.3
info:
  title: Pet Store API
  version: 1.0.0
  description: A simple pet store API
servers:
  - url: http://localhost:8080
    description: Development server
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    status:
                      type: string
                      enum: [available, pending, sold]

Create `production-overlay.yaml`¶

Create an overlay that modifies the API for production:

overlay: 1.0.0
info:
  title: Production Configuration Overlay
  version: 1.0.0
actions:
  # Replace development server with production server
  - target: "$.servers"
    remove: true
  - target: "$"
    update:
      servers:
        - url: https://api.petstore.com
          description: Production server
        - url: https://api-backup.petstore.com
          description: Backup production server

  # Update API info for production
  - target: "$.info"
    update:
      description: "Pet Store API - Production Environment"
      version: "1.1.0"
      contact:
        name: API Support
        url: https://petstore.com/support
        email: api-support@petstore.com

  # Add security scheme
  - target: "$.components"
    remove: true
  - target: "$"
    update:
      components:
        securitySchemes:
          ApiKeyAuth:
            type: apiKey
            in: header
            name: X-API-Key
            description: API key for production access

  # Add security requirement to the GET /pets endpoint
  - target: "$.paths.['/pets'].get"
    update:
      security:
        - ApiKeyAuth: []

Step 2: Apply the Overlay¶

Now let's apply the overlay to transform your API specification:

oas-patch overlay petstore.yaml production-overlay.yaml -o petstore-production.yaml

What This Command Does¶

overlay - The command to apply an overlay
petstore.yaml - Source OpenAPI specification
production-overlay.yaml - Overlay file with modifications
-o petstore-production.yaml - Output file for the result

Step 3: Examine the Results¶

Open petstore-production.yaml to see the transformed API:

openapi: 3.0.3
info:
  title: Pet Store API
  version: 1.1.0
  description: Pet Store API - Production Environment
  contact:
    name: API Support
    url: https://petstore.com/support
    email: api-support@petstore.com
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                    status:
                      type: string
                      enum:
                      - available
                      - pending
                      - sold
      security:
      - ApiKeyAuth: []
servers:
- url: https://api.petstore.com
  description: Production server
- url: https://api-backup.petstore.com
  description: Backup production server
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for production access

Key Changes Applied¶

✅ Servers Updated: Development server replaced with production servers
✅ API Info Enhanced: Version, description, and contact information added
✅ Security Added: API key authentication scheme and requirement added
✅ Structure Preserved: All original endpoints and schemas maintained

Step 4: Validate the Result¶

Verify that your overlay was applied correctly:

# Validate the original overlay file
oas-patch validate production-overlay.yaml

Common CLI Commands¶

Here are the most frequently used commands:

Apply Overlays¶

# Basic overlay application
oas-patch overlay api.yaml overlay.yaml -o result.yaml

# Apply and output to stdout
oas-patch overlay api.yaml overlay.yaml

# Apply with sanitization (remove special characters)
oas-patch overlay api.yaml overlay.yaml --sanitize -o clean-result.yaml

Generate Overlays¶

# Create overlay by comparing two OpenAPI files
oas-patch diff original.yaml modified.yaml -o diff-overlay.yaml

# Generate and output to stdout
oas-patch diff original.yaml modified.yaml

Validation¶

# Validate overlay syntax
oas-patch validate overlay.yaml

# Validate with different error output formats
oas-patch validate overlay.yaml --format yaml
oas-patch validate overlay.yaml --format log

Understanding Overlay Actions¶

The overlay you created uses several types of actions:

1. Remove Action¶

- target: "$.servers"
  remove: true

Purpose: Removes the existing servers array

2. Update Action¶

- target: "$"
  update:
    servers:
      - url: https://api.petstore.com

Purpose: Adds new content to the root of the document

3. Target Selection¶

"$" - Root of the document
"$.servers" - The servers array
"$.info" - The info object
"$.paths.['/pets'].get" - Specific endpoint operation

Next Steps¶

Congratulations! You've successfully applied your first overlay. Here's what to explore next:

🎯 Immediate Next Steps¶

Your First Overlay - Create an overlay from scratch
Core Concepts - Understand overlay fundamentals
Bundle Management - Organize multiple overlays

🚀 Advanced Topics¶

Template Engine - Dynamic content generation

Tips for Success¶

💡 Start Small: Begin with simple overlays and gradually add complexity
🔍 Use Validation: Always validate your overlays before applying them
📚 Read Examples: Check out the examples directory for inspiration
🧪 Test Thoroughly: Test overlays in development before production use
📖 Know JSONPath: Understanding JSONPath will help you target elements precisely