Metadata-Version: 2.4
Name: schemawatch
Version: 0.1.1
Summary: Detect breaking API changes between OpenAPI schemas
Author: Cem Celik
License: MIT
Keywords: openapi,api,schema,breaking-change,cli,ci-cd
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Requires-Dist: colorama>=0.4.6
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"

# SchemaWatch

> Detect breaking API changes before they reach production.
> Works with any OpenAPI file — just run one command.

![PyPI](https://img.shields.io/pypi/v/schemawatch)
![CI](https://github.com/CemCelik79/schemawatch/actions/workflows/ci.yml/badge.svg)
![Python](https://img.shields.io/pypi/pyversions/schemawatch)
![License](https://img.shields.io/github/license/CemCelik79/schemawatch)
![Stars](https://img.shields.io/github/stars/CemCelik79/schemawatch?style=social)

---

## 🎬 Demo

![SchemaWatch Demo](docs/demo.gif)

```bash
python -m schemawatch.cli examples/old.yaml examples/new.yaml
```

---

## 🚀 What is SchemaWatch?

SchemaWatch compares two OpenAPI schemas and detects breaking API changes automatically.

It is designed to be:

- ⚡ Simple
- ⚡ Fast
- ⚡ CI/CD friendly

---

## 🚀 Features

SchemaWatch detects:

- Removed endpoints
- Removed HTTP methods
- Removed schemas
- Removed response fields
- Field type changes
- Fields that became required
- Enum value changes
- Array item type changes

---

## 📦 Installation

```bash
pip install schemawatch
```

---

## ⚙️ Usage

```bash
# Basic usage
python -m schemawatch.cli examples/old.yaml examples/new.yaml

# JSON output
python -m schemawatch.cli examples/old.yaml examples/new.yaml --format json

# Markdown output
python -m schemawatch.cli examples/old.yaml examples/new.yaml --format markdown

# Save to file
python -m schemawatch.cli examples/old.yaml examples/new.yaml --format json --output result.json

# Quiet mode (CI use)
python -m schemawatch.cli examples/old.yaml examples/new.yaml --quiet
```

---

## 🧑‍💻 Real-world usage

```bash
python -m schemawatch.cli openapi_old.yaml openapi.yaml
python -m schemawatch.cli api/v1/openapi.yaml api/v2/openapi.yaml
```

---

## 🧪 Example Output

```
====================================
🚨 SchemaWatch Report
====================================

Breaking changes detected: 5

── CRITICAL (2)
🔴 Endpoint removed: /orders
🔴 Method removed: GET /users

── WARNING (3)
🟡 Response field removed: User.email
🟡 Field type changed: User.id integer -> string
🟡 Field became required: User.id

------------------------------------
Summary:
- Total changes: 5
- Critical: 2
- Warning:  3
- Info:     0
------------------------------------
```

---

## 🔁 CI/CD Integration

SchemaWatch is designed to run in CI pipelines.

```bash
python -m schemawatch.cli openapi_old.yaml openapi.yaml
```

- Exit code `1` → breaking changes detected ❌
- Exit code `0` → no breaking changes ✅

---

## ⚙️ GitHub Actions Example

```yaml
- name: Check API breaking changes
  run: python -m schemawatch.cli openapi_old.yaml openapi.yaml
```

---

## 💬 PR Comment Integration

Automatically comments on pull requests:

```
⚠ Breaking API changes detected:

🔴 Endpoint removed: /orders
🟡 Field type changed: User.id integer -> string
```

---

## 🤔 Why not oasdiff / openapi-diff?

| Feature        | SchemaWatch         | oasdiff / openapi-diff |
| -------------- | ------------------- | ---------------------- |
| Easy CLI       | ✅ Very simple       | ⚠️ More complex        |
| CI/CD friendly | ✅ Built-in mindset  | ⚠️ Needs config        |
| PR comments    | ✅ Yes               | ❌ Not built-in         |
| Severity levels| ✅ Critical/Warning/Info | ❌ Not built-in    |
| Output         | ✅ Clean & readable  | ⚠️ Verbose             |
| Setup time     | ⚡ 10 seconds        | ⏱️ Longer              |

> SchemaWatch = quick setup + practical usage

---

## 🛠 Roadmap

- [ ] Request body change detection
- [ ] Response status code comparison
- [ ] Nested object comparison improvements
- [ ] Markdown / HTML output
- [ ] Web dashboard

---

## 🤝 Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Open a pull request

---

## 📄 License

This project is licensed under the MIT License.
