oas-patch 0.0.1__tar.gz

oas_patch-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthieu Croissant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oas_patch-0.0.1/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: oas_patch
+Version: 0.0.1
+Summary: A tool to apply overlays to OpenAPI documents.
+Home-page: https://github.com/mcroissant/oas_patcher
+Author: Matthieu Croissant
+Author-email: your.email@example.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jsonpath-ng>=1.7.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

oas_patch-0.0.1/README.md

@@ -0,0 +1,60 @@
+# OpenAPI Specification Patcher
+
+The OpenAPI Specification Patcher (oas-patch) is a command-line utility that allows you to programmatically modify or update OpenAPI specifications using [overlay documents](https://github.com/OAI/Overlay-Specification) . It supports both YAML and JSON formats and provides powerful JSONPath-based targeting for updates and removals.
+
+## Features
+- **JSONPath Support**: Use JSONPath expressions to target specific parts of your OpenAPI document.
+- **Flexible Updates**: Apply updates or remove elements from your OpenAPI specification.
+- **YAML and JSON Support**: Works seamlessly with both YAML and JSON OpenAPI documents.
+- **Sanitization**: Optionally remove special characters from your OpenAPI document.
+
+## Prerequisites
+- Python 3.7 or higher
+- `pip` for managing Python packages
+
+## Installation
+### Install from Source
+Clone the repository and install the tool locally:
+```bash
+git clone https://github.com/your-username/oas-patch
+pip install -e .
+```
+
+## Usage
+The tool provides a simple CLI for applying overlays to OpenAPI documents.
+
+
+### Example Usage
+Apply an overlay to an OpenAPI document and save the result:
+```bash
+oas-patch --openapi openapi.yaml --overlay overlay.yaml --output modified_openapi.yaml
+```
+
+Apply an overlay and print the result to the console:
+```bash
+oas-patch --openapi openapi.json --overlay overlay.json
+```
+
+Sanitize the OpenAPI document while applying the overlay:
+```bash
+oas-patch --openapi openapi.yaml --overlay overlay.yaml --sanitize
+```
+
+## Contributing
+Contributions are welcome! To contribute:
+1. Fork the repository.
+2. Create a new branch for your feature or bugfix.
+3. Submit a pull request with a clear description of your changes.
+
+### Running Tests
+To run the tests, install the development dependencies and execute the test suite:
+```bash
+pip install -r requirements-dev.txt
+pytest
+```
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+This tool was inspired by the need to programmatically manage OpenAPI specifications in a flexible and reusable way. Special thanks to the open-source community for their contributions to JSONPath and YAML parsing libraries.

oas_patch-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oas_patch-0.0.1/setup.py

@@ -0,0 +1,27 @@
+from setuptools import setup, find_packages
+
+setup(
+    name='oas_patch',
+    version='0.0.1',
+    description='A tool to apply overlays to OpenAPI documents.',
+    author='Matthieu Croissant',
+    author_email='your.email@example.com',
+    url='https://github.com/mcroissant/oas_patcher',
+    packages=find_packages(where='src'),
+    package_dir={'': 'src'},
+    install_requires=[
+        'PyYAML>=6.0',
+        'jsonpath-ng>=1.7.0'
+    ],
+    entry_points={
+        'console_scripts': [
+            'oas-patch=oas_patcher_cli:cli',  # Update this to reference the correct module
+        ],
+    },
+    classifiers=[
+        'Programming Language :: Python :: 3',
+        'License :: OSI Approved :: MIT License',
+        'Operating System :: OS Independent',
+    ],
+    python_requires='>=3.7',
+)

oas_patch-0.0.1/src/oas_patch.egg-info/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: oas_patch
+Version: 0.0.1
+Summary: A tool to apply overlays to OpenAPI documents.
+Home-page: https://github.com/mcroissant/oas_patcher
+Author: Matthieu Croissant
+Author-email: your.email@example.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jsonpath-ng>=1.7.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

oas_patch-0.0.1/src/oas_patch.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+setup.py
+src/oas_patch.egg-info/PKG-INFO
+src/oas_patch.egg-info/SOURCES.txt
+src/oas_patch.egg-info/dependency_links.txt
+src/oas_patch.egg-info/entry_points.txt
+src/oas_patch.egg-info/requires.txt
+src/oas_patch.egg-info/top_level.txt
+tests/test_file_utils.py
+tests/test_integration_complex.py
+tests/test_integration_medium.py
+tests/test_integration_simple.py
+tests/test_oas_patcher_cli.py
+tests/test_overlay.py

oas_patch-0.0.1/src/oas_patch.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

oas_patch-0.0.1/src/oas_patch.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+oas-patch = oas_patcher_cli:cli

oas_patch-0.0.1/src/oas_patch.egg-info/requires.txt

@@ -0,0 +1,2 @@
+PyYAML>=6.0
+jsonpath-ng>=1.7.0

oas_patch-0.0.1/src/oas_patch.egg-info/top_level.txt

@@ -0,0 +1 @@
+

oas_patch-0.0.1/tests/test_file_utils.py

@@ -0,0 +1,133 @@
+import pytest
+from unittest.mock import mock_open, patch
+from src.file_utils import (
+    load_yaml, load_json, load_file,
+    save_yaml, save_json, save_file,
+    sanitize_content
+)
+
+
+def test_load_yaml_valid():
+    """Test loading a valid YAML file."""
+    yaml_content = "key: value"
+    with patch("builtins.open", mock_open(read_data=yaml_content)):
+        result = load_yaml("test.yaml")
+    assert result == {"key": "value"}
+
+
+def test_load_yaml_invalid():
+    """Test loading an invalid YAML file."""
+    invalid_yaml = "key: value: another"
+    with patch("builtins.open", mock_open(read_data=invalid_yaml)):
+        with pytest.raises(ValueError, match="Invalid YAML format"):
+            load_yaml("test.yaml")
+
+
+def test_load_yaml_file_not_found():
+    """Test loading a non-existent YAML file."""
+    with patch("builtins.open", side_effect=FileNotFoundError):
+        with pytest.raises(FileNotFoundError, match="File not found"):
+            load_yaml("missing.yaml")
+
+
+def test_load_json_valid():
+    """Test loading a valid JSON file."""
+    json_content = '{"key": "value"}'
+    with patch("builtins.open", mock_open(read_data=json_content)):
+        result = load_json("test.json")
+    assert result == {"key": "value"}
+
+
+def test_load_json_invalid():
+    """Test loading an invalid JSON file."""
+    invalid_json = '{"key": "value"'
+    with patch("builtins.open", mock_open(read_data=invalid_json)):
+        with pytest.raises(ValueError, match="Invalid JSON format"):
+            load_json("test.json")
+
+
+def test_load_json_file_not_found():
+    """Test loading a non-existent JSON file."""
+    with patch("builtins.open", side_effect=FileNotFoundError):
+        with pytest.raises(FileNotFoundError, match="File not found"):
+            load_json("missing.json")
+
+
+def test_load_file_yaml():
+    """Test loading a YAML file using load_file."""
+    yaml_content = "key: value"
+    with patch("builtins.open", mock_open(read_data=yaml_content)):
+        result = load_file("test.yaml")
+    assert result == {"key": "value"}
+
+
+def test_load_file_json():
+    """Test loading a JSON file using load_file."""
+    json_content = '{"key": "value"}'
+    with patch("builtins.open", mock_open(read_data=json_content)):
+        result = load_file("test.json")
+    assert result == {"key": "value"}
+
+
+def test_load_file_unsupported_format():
+    """Test loading a file with an unsupported format."""
+    with pytest.raises(ValueError, match="Unsupported file format"):
+        load_file("test.txt")
+
+
+def test_save_yaml():
+    """Test saving data to a YAML file."""
+    data = {"key": "value"}
+    with patch("builtins.open", mock_open()) as mocked_file:
+        save_yaml(data, "test.yaml")
+        mocked_file.assert_called_once_with("test.yaml", "w", encoding="utf-8")
+        # Combine all write calls into a single string and verify the content
+        written_content = "".join(call.args[0] for call in mocked_file().write.call_args_list)
+        assert written_content == "key: value\n"
+
+
+def test_save_json():
+    """Test saving data to a JSON file."""
+    data = {"key": "value"}
+    with patch("builtins.open", mock_open()) as mocked_file:
+        save_json(data, "test.json")
+        mocked_file.assert_called_once_with("test.json", "w", encoding="utf-8")
+        # Combine all write calls into a single string and verify the content
+        written_content = "".join(call.args[0] for call in mocked_file().write.call_args_list)
+        assert written_content == '{\n  "key": "value"\n}'
+
+
+def test_save_file_yaml():
+    """Test saving data to a YAML file using save_file."""
+    data = {"key": "value"}
+    with patch("builtins.open", mock_open()) as mocked_file:
+        save_file(data, "test.yaml")
+        mocked_file.assert_called_once_with("test.yaml", "w", encoding="utf-8")
+        # Combine all write calls into a single string and verify the content
+        written_content = "".join(call.args[0] for call in mocked_file().write.call_args_list)
+        assert written_content == "key: value\n"
+
+
+def test_save_file_json():
+    """Test saving data to a JSON file using save_file."""
+    data = {"key": "value"}
+    with patch("builtins.open", mock_open()) as mocked_file:
+        save_file(data, "test.json")
+        mocked_file.assert_called_once_with("test.json", "w", encoding="utf-8")
+        # Combine all write calls into a single string and verify the content
+        written_content = "".join(call.args[0] for call in mocked_file().write.call_args_list)
+        assert written_content == '{\n  "key": "value"\n}'
+
+
+def test_save_file_unsupported_format():
+    """Test saving data to an unsupported file format."""
+    data = {"key": "value"}
+    with pytest.raises(ValueError, match="Unsupported file format"):
+        save_file(data, "test.txt")
+
+
+def test_sanitize_content():
+    """Test removing non-printable characters from a string."""
+    content = "Valid\x00 content\x1F with invalid\x7F characters"
+    sanitized = sanitize_content(content)
+    assert sanitized == "Valid content with invalid characters"

oas_patch-0.0.1/tests/test_integration_complex.py

@@ -0,0 +1,43 @@
+import os
+import tempfile
+import yaml
+import pytest
+from src.oas_patcher_cli import cli
+from unittest.mock import patch
+
+
+@pytest.mark.parametrize("test_case", [
+    {
+        "name": "petstore",
+        "openapi_file": "tests/samples/complex/petstore/openapi.yaml",
+        "overlay_file": "tests/samples/complex/petstore/overlay.yaml",
+        "expected_file": "tests/samples/complex/petstore/output.yaml",
+    }
+])
+def test_integration_file_based(test_case, capsys):
+    """Test the CLI using input and expected output files."""
+    with tempfile.NamedTemporaryFile(suffix=".yaml", delete=False) as temp_output:
+        temp_output.close()
+
+        # Mock CLI arguments
+        with patch('sys.argv', [
+            'oas-patch',
+            '--openapi', test_case["openapi_file"],
+            '--overlay', test_case["overlay_file"],
+            '--output', temp_output.name
+        ]):
+            cli()
+
+        # Load the CLI output
+        with open(temp_output.name, 'r', encoding='utf-8') as output_file:
+            output_data = yaml.safe_load(output_file)
+
+        # Load the expected output
+        with open(test_case["expected_file"], 'r', encoding='utf-8') as expected_file:
+            expected_data = yaml.safe_load(expected_file)
+
+        # Compare the output with the expected data
+        assert output_data == expected_data, f"Test case '{test_case['name']}' failed."
+
+        # Clean up the temporary file
+        os.remove(temp_output.name)

oas_patch-0.0.1/tests/test_integration_medium.py

@@ -0,0 +1,73 @@
+import os
+import tempfile
+import yaml
+import pytest
+from src.oas_patcher_cli import cli
+from unittest.mock import patch
+
+
+@pytest.mark.parametrize("test_case", [
+    {
+        "name": "array_update",
+        "openapi_file": "tests/samples/medium/array_update/openapi.yaml",
+        "overlay_file": "tests/samples/medium/array_update/overlay.yaml",
+        "expected_file": "tests/samples/medium/array_update/output.yaml",
+    },
+    {
+        "name": "array_remove",
+        "openapi_file": "tests/samples/medium/array_remove/openapi.yaml",
+        "overlay_file": "tests/samples/medium/array_remove/overlay.yaml",
+        "expected_file": "tests/samples/medium/array_remove/output.yaml",
+    },
+    {
+        "name": "remove_update",
+        "openapi_file": "tests/samples/medium/remove_update/openapi.yaml",
+        "overlay_file": "tests/samples/medium/remove_update/overlay.yaml",
+        "expected_file": "tests/samples/medium/remove_update/output.yaml",
+    },
+    {
+        "name": "structured_overlay",
+        "openapi_file": "tests/samples/medium/structured_overlay/openapi.yaml",
+        "overlay_file": "tests/samples/medium/structured_overlay/overlay.yaml",
+        "expected_file": "tests/samples/medium/structured_overlay/output.yaml",
+    },
+    {
+        "name": "targeted_overlay",
+        "openapi_file": "tests/samples/medium/targeted_overlay/openapi.yaml",
+        "overlay_file": "tests/samples/medium/targeted_overlay/overlay.yaml",
+        "expected_file": "tests/samples/medium/targeted_overlay/output.yaml",
+    },
+    {
+        "name": "wildcard_overlay",
+        "openapi_file": "tests/samples/medium/wildcard_overlay/openapi.yaml",
+        "overlay_file": "tests/samples/medium/wildcard_overlay/overlay.yaml",
+        "expected_file": "tests/samples/medium/wildcard_overlay/output.yaml",
+    }
+])
+def test_integration_file_based(test_case, capsys):
+    """Test the CLI using input and expected output files."""
+    with tempfile.NamedTemporaryFile(suffix=".yaml", delete=False) as temp_output:
+        temp_output.close()
+
+        # Mock CLI arguments
+        with patch('sys.argv', [
+            'oas-patch',
+            '--openapi', test_case["openapi_file"],
+            '--overlay', test_case["overlay_file"],
+            '--output', temp_output.name
+        ]):
+            cli()
+
+        # Load the CLI output
+        with open(temp_output.name, 'r', encoding='utf-8') as output_file:
+            output_data = yaml.safe_load(output_file)
+
+        # Load the expected output
+        with open(test_case["expected_file"], 'r', encoding='utf-8') as expected_file:
+            expected_data = yaml.safe_load(expected_file)
+
+        # Compare the output with the expected data
+        assert output_data == expected_data, f"Test case '{test_case['name']}' failed."
+
+        # Clean up the temporary file
+        os.remove(temp_output.name)

oas_patch-0.0.1/tests/test_integration_simple.py

@@ -0,0 +1,61 @@
+import os
+import tempfile
+import yaml
+import pytest
+from src.oas_patcher_cli import cli
+from unittest.mock import patch
+
+
+@pytest.mark.parametrize("test_case", [
+    {
+        "name": "update",
+        "openapi_file": "tests/samples/simple/update/openapi.yaml",
+        "overlay_file": "tests/samples/simple/update/overlay.yaml",
+        "expected_file": "tests/samples/simple/update/output.yaml",
+    },
+    {
+        "name": "remove",
+        "openapi_file": "tests/samples/simple/remove/openapi.yaml",
+        "overlay_file": "tests/samples/simple/remove/overlay.yaml",
+        "expected_file": "tests/samples/simple/remove/output.yaml",
+    },
+    {
+        "name": "multi_action",
+        "openapi_file": "tests/samples/simple/multi_action/openapi.yaml",
+        "overlay_file": "tests/samples/simple/multi_action/overlay.yaml",
+        "expected_file": "tests/samples/simple/multi_action/output.yaml",
+    },
+    {
+        "name": "no_match",
+        "openapi_file": "tests/samples/simple/no_match/openapi.yaml",
+        "overlay_file": "tests/samples/simple/no_match/overlay.yaml",
+        "expected_file": "tests/samples/simple/no_match/output.yaml",
+    }
+])
+def test_integration_file_based(test_case, capsys):
+    """Test the CLI using input and expected output files."""
+    with tempfile.NamedTemporaryFile(suffix=".yaml", delete=False) as temp_output:
+        temp_output.close()
+
+        # Mock CLI arguments
+        with patch('sys.argv', [
+            'oas-patch',
+            '--openapi', test_case["openapi_file"],
+            '--overlay', test_case["overlay_file"],
+            '--output', temp_output.name
+        ]):
+            cli()
+
+        # Load the CLI output
+        with open(temp_output.name, 'r', encoding='utf-8') as output_file:
+            output_data = yaml.safe_load(output_file)
+
+        # Load the expected output
+        with open(test_case["expected_file"], 'r', encoding='utf-8') as expected_file:
+            expected_data = yaml.safe_load(expected_file)
+
+        # Compare the output with the expected data
+        assert output_data == expected_data, f"Test case '{test_case['name']}' failed."
+
+        # Clean up the temporary file
+        os.remove(temp_output.name)

oas_patch-0.0.1/tests/test_oas_patcher_cli.py

@@ -0,0 +1,108 @@
+import pytest
+import yaml
+from src.oas_patcher_cli import cli
+
+
+@pytest.fixture
+def mock_load_file(mocker):
+    """Mock the load_file function."""
+    return mocker.patch('src.oas_patcher_cli.load_file')
+
+
+@pytest.fixture
+def mock_save_file(mocker):
+    """Mock the save_file function."""
+    return mocker.patch('src.oas_patcher_cli.save_file')
+
+
+@pytest.fixture
+def mock_apply_overlay(mocker):
+    """Mock the apply_overlay function."""
+    return mocker.patch('src.oas_patcher_cli.apply_overlay')
+
+
+@pytest.fixture
+def setup_mocks(mock_load_file, mock_apply_overlay):
+    """Set up common mock behavior for load_file and apply_overlay."""
+    mock_load_file.side_effect = [
+        {"openapi": "3.0.3", "info": {"title": "Sample API"}},
+        {"actions": [{"target": "$.info", "update": {"title": "Updated API"}}]},
+    ]
+    mock_apply_overlay.return_value = {"openapi": "3.0.3", "info": {"title": "Updated API"}}
+
+
+def run_cli_with_args(mocker, args):
+    """Helper function to run the CLI with specific arguments."""
+    mocker.patch('sys.argv', ['oas-patch'] + args)
+    cli()
+
+
+def assert_load_file_calls(mock_load_file, sanitize=False):
+    """Helper function to assert calls to load_file."""
+    mock_load_file.assert_any_call('openapi.yaml', sanitize)
+    mock_load_file.assert_any_call('overlay.yaml')
+
+
+def assert_apply_overlay_call(mock_apply_overlay):
+    """Helper function to assert calls to apply_overlay."""
+    mock_apply_overlay.assert_called_once_with(
+        {"openapi": "3.0.3", "info": {"title": "Sample API"}},
+        {"actions": [{"target": "$.info", "update": {"title": "Updated API"}}]}
+    )
+
+
+def assert_save_file_call(mock_save_file, output_file):
+    """Helper function to assert calls to save_file."""
+    mock_save_file.assert_called_once_with(
+        {"openapi": "3.0.3", "info": {"title": "Updated API"}}, output_file
+    )
+
+
+def test_cli_output_to_file(setup_mocks, mock_save_file, mock_load_file, mock_apply_overlay, mocker):
+    """Test the CLI with output to a file."""
+    run_cli_with_args(mocker, ['--openapi', 'openapi.yaml', '--overlay', 'overlay.yaml', '--output', 'output.yaml'])
+
+    assert_load_file_calls(mock_load_file, sanitize=False)
+    assert_apply_overlay_call(mock_apply_overlay)
+    assert_save_file_call(mock_save_file, 'output.yaml')
+
+
+def test_cli_output_to_console(setup_mocks, mock_load_file, mock_apply_overlay, mocker, capsys):
+    """Test the CLI with output to the console."""
+    run_cli_with_args(mocker, ['--openapi', 'openapi.yaml', '--overlay', 'overlay.yaml'])
+
+    assert_load_file_calls(mock_load_file, sanitize=False)
+    assert_apply_overlay_call(mock_apply_overlay)
+
+    captured = capsys.readouterr()
+    assert yaml.safe_load(captured.out) == {"openapi": "3.0.3", "info": {"title": "Updated API"}}
+
+
+def test_cli_missing_required_arguments(mocker):
+    """Test the CLI with missing required arguments."""
+    mocker.patch('sys.argv', ['oas-patch'])
+
+    with pytest.raises(SystemExit) as excinfo:
+        cli()
+
+    assert excinfo.value.code == 2  # argparse exits with code 2 for missing arguments
+
+
+def test_cli_with_sanitize_flag(setup_mocks, mock_load_file, mock_apply_overlay, mocker):
+    """Test the CLI with the --sanitize flag."""
+    run_cli_with_args(mocker, ['--openapi', 'openapi.yaml', '--overlay', 'overlay.yaml', '--sanitize'])
+
+    assert_load_file_calls(mock_load_file, sanitize=True)
+    assert_apply_overlay_call(mock_apply_overlay)
+
+
+def test_help_command(mocker, capsys):
+    """Test the CLI help message."""
+    mocker.patch('sys.argv', ['oas-patch', '--help'])
+
+    with pytest.raises(SystemExit) as excinfo:
+        cli()
+
+    captured = capsys.readouterr()
+    assert "Apply an OpenAPI Overlay to your OpenAPI document." in captured.out
+    assert excinfo.value.code == 0  # Ensure the CLI exits with code 0 for help

oas_patch-0.0.1/tests/test_overlay.py

@@ -0,0 +1,242 @@
+import pytest
+from src.overlay import apply_overlay, deep_update
+
+
+def test_apply_overlay_update_action():
+    """Test applying an overlay with update actions."""
+    openapi_doc = {
+        "paths": {
+            "/example": {
+                "get": {
+                    "summary": "Original summary"
+                }
+            }
+        }
+    }
+    overlay = {
+        "actions": [
+            {
+                "target": "$.paths['/example'].get",
+                "update": {
+                    "summary": "Updated summary"
+                }
+            }
+        ]
+    }
+    result = apply_overlay(openapi_doc, overlay)
+    assert result["paths"]["/example"]["get"]["summary"] == "Updated summary"
+
+
+def test_apply_overlay_remove_action():
+    """Test applying an overlay with remove actions."""
+    openapi_doc = {
+        "paths": {
+            "/example": {
+                "get": {
+                    "summary": "Original summary"
+                }
+            }
+        }
+    }
+    overlay = {
+        "actions": [
+            {
+                "target": "$.paths['/example'].get",
+                "remove": True
+            }
+        ]
+    }
+    result = apply_overlay(openapi_doc, overlay)
+    assert "get" not in result["paths"]["/example"]
+
+
+def test_apply_overlay_no_matching_target():
+    """Test applying an overlay with no matching JSONPath targets."""
+    openapi_doc = {
+        "paths": {
+            "/example": {
+                "get": {
+                    "summary": "Original summary"
+                }
+            }
+        }
+    }
+    overlay = {
+        "actions": [
+            {
+                "target": "$.paths['/nonexistent'].get",
+                "update": {
+                    "summary": "Updated summary"
+                }
+            }
+        ]
+    }
+    result = apply_overlay(openapi_doc, overlay)
+    assert result == openapi_doc  # No changes should be made
+
+
+def test_apply_overlay_empty_actions():
+    """Test applying an overlay with an empty actions list."""
+    openapi_doc = {
+        "paths": {
+            "/example": {
+                "get": {
+                    "summary": "Original summary"
+                }
+            }
+        }
+    }
+    overlay = {
+        "actions": []
+    }
+    result = apply_overlay(openapi_doc, overlay)
+    assert result == openapi_doc  # No changes should be made
+
+
+def test_deep_update_nested_keys():
+    """Test deep updating a dictionary with nested keys."""
+    target = {
+        "key1": {
+            "subkey1": "value1"
+        }
+    }
+    updates = {
+        "key1": {
+            "subkey2": "value2"
+        }
+    }
+    deep_update(target, updates)
+    assert target["key1"]["subkey1"] == "value1"
+    assert target["key1"]["subkey2"] == "value2"
+
+
+def test_deep_update_overwrite_keys():
+    """Test deep updating a dictionary with overwriting keys."""
+    target = {
+        "key1": {
+            "subkey1": "value1"
+        }
+    }
+    updates = {
+        "key1": {
+            "subkey1": "new_value1"
+        }
+    }
+    deep_update(target, updates)
+    assert target["key1"]["subkey1"] == "new_value1"
+
+
+def test_deep_update_add_new_keys():
+    """Test deep updating a dictionary by adding new keys."""
+    target = {
+        "key1": {
+            "subkey1": "value1"
+        }
+    }
+    updates = {
+        "key2": {
+            "subkey2": "value2"
+        }
+    }
+    deep_update(target, updates)
+    assert target["key1"]["subkey1"] == "value1"
+    assert target["key2"]["subkey2"] == "value2"
+
+
+def test_apply_overlay_update_root():
+    """Test applying an overlay with an update action targeting the root."""
+    openapi_doc = {
+        "openapi": "3.0.3",
+        "info": {
+            "title": "Sample API",
+            "version": "1.0.0"
+        }
+    }
+    overlay = {
+        "actions": [
+            {
+                "target": "$",  # Root of the document
+                "update": {
+                    "description": "This is a root-level description"
+                }
+            }
+        ]
+    }
+    result = apply_overlay(openapi_doc, overlay)
+    assert result["description"] == "This is a root-level description"
+    assert result["openapi"] == "3.0.3"  # Ensure existing keys are preserved
+
+
+def test_apply_overlay_remove_root():
+    """Test applying an overlay with a remove action targeting the root."""
+    openapi_doc = {
+        "openapi": "3.0.3",
+        "info": {
+            "title": "Sample API",
+            "version": "1.0.0"
+        }
+    }
+    overlay = {
+        "actions": [
+            {
+                "target": "$",  # Root of the document
+                "remove": True
+            }
+        ]
+    }
+    with pytest.raises(ValueError, match="Cannot remove the root of the document"):
+        apply_overlay(openapi_doc, overlay)
+
+
+def test_apply_overlay_non_dict_update_root():
+    """Test applying an overlay with a non-dict update action targeting the root."""
+    openapi_doc = {
+        "openapi": "3.0.3",
+        "info": {
+            "title": "Sample API",
+            "version": "1.0.0"
+        }
+    }
+    overlay = {
+        "actions": [
+            {
+                "target": "$",  # Root of the document
+                "update": "Invalid root update"
+            }
+        ]
+    }
+    with pytest.raises(ValueError, match="Cannot perform non-dict update on the root of the document"):
+        apply_overlay(openapi_doc, overlay)
+
+
+def test_apply_overlay_merge_dict_with_array():
+    """Test applying an overlay with a non-dict update action targeting the root."""
+    openapi_doc = {
+        "openapi": "3.0.3",
+        "info": {
+            "title": "Sample API",
+            "version": "1.0.0"
+        },
+        "paths": {
+            "/example": {
+                "get": {
+                    "summary": "Original summary",
+                    "security": [
+                        {
+                            "api_key": []
+                        }
+                    ]
+                }
+            }
+        }
+    }
+    overlay = {
+        "actions": [
+            {
+                "target": "$.paths.*.get",  # Root of the document
+                "update": {"security": [{"oauth2": []}]}
+            }
+        ]
+    }
+    result = apply_overlay(openapi_doc, overlay)
+    assert len(result["paths"]["/example"]["get"]["security"]) == 2  # Ensure both security definitions are present