OpenAPI Spec & Live Response Verification Script

Documentation becomes a liability when code evolves but technical guides remain static. To prevent API drift, outdated request parameters, and AI hallucination, I don't rely solely on staging documentation or passive OpenAPI JSON specs.

Before documenting an endpoint, I run automated schema validation scripts against live responses to verify:

1. Response Schema Compliance: Live JSON responses match the published OpenAPI 3.0/3.1 contract.
2. HTTP Status & Error Behaviors: Expected error payloads (400, 401, 429) match official error schemas.
3. Authentication & Rate Limits: Header constraints and rate-limit headers (X-RateLimit-Remaining) return active telemetry.

---

Python Verification Script (verify_api_schema.py)

This script fetches a target OpenAPI specification, executes HTTP calls against live endpoints, and validates the returned payload against expected JSON schemas.

import sys
import yaml
import requests
from jsonschema import validate, ValidationError

def load_openapi_spec(spec_url: str) -> dict:
    """Fetch and parse OpenAPI YAML/JSON specification."""
    response = requests.get(spec_url)
    response.raise_for_status()
    return yaml.safe_load(response.text)

def verify_endpoint(endpoint_url: str, expected_schema: dict, headers: dict = None) -> bool:
    """Execute live API request and validate JSON response against schema."""
    print(f"[TESTING] GET {endpoint_url}...")

    try:
        res = requests.get(endpoint_url, headers=headers or {}, timeout=10)
        print(f"[STATUS] HTTP {res.status_code}")

        # Check HTTP Success
        if res.status_code != 200:
            print(f"[FAIL] Unexpected status code: {res.status_code}")
            return False

        # Validate Payload against OpenAPI Schema
        payload = res.json()
        validate(instance=payload, schema=expected_schema)
        print("[PASS] Response payload perfectly matches OpenAPI JSON Schema.")
        return True

    except ValidationError as ve:
        print(f"[SCHEMA ERROR] Field '{'.'.join(str(p) for p in ve.path)}': {ve.message}")
        return False
    except Exception as e:
        print(f"[EXECUTION ERROR] {str(e)}")
        return False

if __name__ == "__main__":
    # Target Public REST Endpoint Example (GitHub Users API)
    LIVE_ENDPOINT = "https://api.github.com/users/octocat"

    # OpenAPI User Schema Subset
    EXPECTED_USER_SCHEMA = {
        "type": "object",
        "required": ["login", "id", "node_id", "avatar_url", "type"],
        "properties": {
            "login": {"type": "string"},
            "id": {"type": "integer"},
            "node_id": {"type": "string"},
            "avatar_url": {"type": "string"},
            "type": {"type": "string"}
        }
    }

    success = verify_endpoint(LIVE_ENDPOINT, EXPECTED_USER_SCHEMA)
    sys.exit(0 if success else 1)

---

Validation Output Sample

Running the script against the live GitHub API:

[TESTING] GET https://api.github.com/users/octocat...
[STATUS] HTTP 200
[PASS] Response payload perfectly matches OpenAPI JSON Schema.
[INFO] Execution finished. Success: True

---

Troubleshooting

If you run this in Google Colab, the last line (sys.exit(0 if success else 1)) will throw an error because it tries to exit the kernel. Replace it with:

print(f"[INFO] Execution finished. Success: {success}")

---

Why This Matters for Technical Documentation

Zero Hallucination

Code examples provided in technical guides are tested against live responses before publication. No copied-from-docs examples that silently drift from reality.

Docs-as-Code Native

Integrates directly into GitHub Actions or GitLab CI/CD pipelines to trigger documentation build alerts whenever an API endpoint breaks schema contract.

AI Search Ready

When LLMs retrieve your documentation, they get code that actually runs — not examples that hallucinate parameters or return shapes that haven't existed in two releases.

---

Stack

• Python 3.11+
• requests — HTTP client
• jsonschema — JSON Schema validation (Draft 7/2020-12)
• PyYAML — OpenAPI spec parsing (YAML/JSON)

---

How to Use This in Your Workflow

1. Add to CI/CD: Run as a pre-deploy check on your API repo
2. Gate documentation builds: Fail the docs build if any endpoint validation fails
3. Schedule nightly: Catch drift from third-party APIs you depend on
4. Extend for auth: Add OAuth/JWT token handling for protected endpoints

---

This verification script is part of my standard workflow for every API reference and developer guide I produce. If you're building technical documentation for an API, web3 protocol, or developer tool — let's make sure the code examples actually work.