OpenAPI linter and diff CLI
Lint JSON or YAML specs, check diffs, and export SARIF in Python.
Common CLI commands
Zero external packages required on Linux, macOS, and Windows runners.
# Lint YAML or JSON OpenAPI specs with an industry preset python3 api_validator.py --spec examples/orders-api-good.openapi.yaml --preset stripe-style # Detect breaking contract changes between two OpenAPI revisions python3 api_validator.py --diff openapi.base.json openapi.head.json --format markdown # Export SARIF 2.1.0 for GitHub Code Scanning python3 api_validator.py --spec openapi.json --format sarif --output api-lint.sarif
Built-in rule presets
Select a baseline profile in presets/ or customize rules in .api-rules.json.
| Preset | Primary focus | Key rules promoted to error |
|---|---|---|
google-aip | URI and resource consistency | ADP-002 (kebab-case), ADP-011 (cursors), ADP-017 (operationId) |
stripe-style | Payments and developer UX | ADP-012 (Idempotency-Key), ADP-013 (429), ADP-019 (examples) |
owasp-api-top10 | Security gate | ADP-010, ADP-014, ADP-015, ADP-016, ADP-021 |
strict-public-api | Zero-warning release gate | Fails on warnings (fail_on: warning) across naming and docs |