api-contract-testing

name	api-contract-testing
description	Validate an API contract against an OpenAPI 3.x specification (JSON or YAML) and an optional manifest of expected endpoints. Script api_contract.py enumerates operations (paths + webhooks), checks spec internal consistency (unresolved $refs, duplicates, missing responses), compares the manifest against the spec offline, and in live mode probes each manifest endpoint over HTTP and compares the actual status with the expected one. Pure Python 3 stdlib (argparse, json, pathlib, sys, urllib.request) with a built-in minimal YAML subset parser — no PyYAML, no requests. Emits a machine-readable JSON report (endpoints_count, missing_from_spec, contract_violations, conformant, errors) and uses exit codes 0/1/2. Closes the loop for api-doc-generator and test-generator.
when_to_use	Use to CHECK that a spec or a running API matches its promised contract — offline spec consistency, manifest coverage, or live status-code probes. Load when the user says: api contract testing, validate openapi spec, spec vs manifest, endpoint coverage, does the API match the spec, проверь контракт API, контрактное тестирование, валидация openapi. Do NOT auto-load for authoring the spec (use api-doc-generator) or writing tests (use test-generator).
license	MIT
metadata	{"author":"best","version":"1.0.0","compatibility":"Requires Python 3 stdlib only; no third-party packages, no network beyond urllib (and none in --offline mode)"}

API Contract Testing — validate an OpenAPI spec against expected endpoints

Load this skill when you need to check that a running API (or a spec on disk) actually matches the contract it promises. It is the verification counterpart of api-doc-generator (which writes the spec) and test-generator (which writes the tests): this skill checks the spec against a manifest of expected endpoints and, optionally, against the live API.

The tool is pure Python 3 stdlib — no PyYAML, no requests, no pip install. It reads an OpenAPI 3.x document from a file (.json or .yaml) or a URL, enumerates every declared operation (under paths and webhooks), checks the spec's internal consistency, and compares it against an optional manifest file. In --offline mode it never touches the network; in live mode it probes each manifest endpoint over HTTP and compares the actual status code with the expected one.

Triggers

Load this skill when the request matches any of these (EN / RU):

• "api contract testing", "contract test", "check the API against the spec"
• "validate openapi spec", "spec vs manifest", "endpoint coverage"
• "проверь контракт API", "тест контракта", "сверь спецификацию с API"
• "валидация openapi", "проверка эндпоинтов", "контрактное тестирование"
• "does the API match the spec", "missing endpoints", "expected status codes"

DO NOT USE FOR: generating the OpenAPI spec (use api-doc-generator); writing the tests (use test-generator). This skill only checks contracts, it does not author them.

---

The api_contract.py script

scripts/api_contract.py — pure Python 3 stdlib (no dependencies).

Mode	Command
Offline, JSON report	python3 api_contract.py --spec openapi.json --offline --json
Offline + manifest	python3 api_contract.py --spec openapi.yaml --manifest endpoints.txt --offline
Live checks	python3 api_contract.py --spec openapi.json --manifest endpoints.txt --base-url https://api.example.com
Spec from URL	python3 api_contract.py --spec-url https://example.com/openapi.json --manifest endpoints.txt