oas-patch 0.6.0

A complete cli/lib to apply overlays to OpenAPI documents, powering your ci/cd and API lifecycle

OAS Patcher

A powerful command-line tool and Python library for working with OpenAPI Specification (OAS) Overlays. Modify and enhance your OpenAPI documents using a declarative overlay approach - no manual editing of large spec files needed!

Key Features

🎯 Overlay System - Apply targeted modifications to OpenAPI documents
📋 Copy Action - Duplicate schemas and components within your API (Overlay 1.1)
📦 Bundle Management - Organize multiple overlays into reusable bundles
🌍 Environment Support - Different configurations for dev, staging, production
🔧 Template Engine - Use variables and dynamic content with Jinja2
✅ Validation - Comprehensive validation for overlays and configurations

Supports OpenAPI Overlay Specification 1.0 and 1.1 - Use the latest features or maintain backward compatibility.

View all features in documentation →

Quick Start

Installation

pip install oas-patch

Basic Usage

1. Apply an Overlay

oas-patch overlay openapi.yaml overlay.yaml -o modified.yaml

2. Generate an Overlay (Diff)

oas-patch diff original.yaml modified.yaml -o overlay.yaml

3. Validate an Overlay

oas-patch validate overlay.yaml

Example

# overlay.yaml
overlay: 1.1.0
info:
  title: Production Environment Overlay
  version: 1.0.0
  description: Configures the API for production use
actions:
  # Update server URL

  - target: "$"
    update:
      servers:
        - url: https://api.production.com
  
  # Copy a schema to create a new one (Overlay 1.1 feature)
  - target: "$.components.schemas.AdminUser"
    copy: "$.components.schemas.User"
    description: Create AdminUser schema based on User schema

Documentation

• 📚 Full Documentation
• 🚀 Getting Started Guide
• 💡 Core Concepts

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.