Versioning Tools

# OpenAPI 3.0 with versioning
openapi: 3.0.0
info:
  title: User API
  version: 2.0.0
  description: "User management API v2. See [migration guide](/docs/migration-v2)"
  x-deprecation-info:
    v1: { sunset: "2026-12-31", migration: "/docs/migration-v2" }

servers:
  - url: https://api.example.com/v2
    description: Production v2
  - url: https://api.example.com/v1
    description: "Production v1 (deprecated)"
    x-deprecated: true

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: cursor
          in: query
          schema: { type: string }
          x-version-added: "2.0.0"
        - name: page
          in: query
          schema: { type: integer }
          x-version-deprecated: "2.0.0"

# Automated breaking change detection
import json
import jsonschema

class VersionDiffTracker:
    """Track API spec changes between versions."""

    def __init__(self, old_spec, new_spec):
        self.old = old_spec
        self.new = new_spec

    def detect_breaking_changes(self):
        breaking = []
        for path, methods in self.new['paths'].items():
            old_path = self.old['paths'].get(path)
            if not old_path and path not in self.old['paths']:
                continue  # New endpoint is additive

            for method in ['get', 'post', 'put', 'delete']:
                old_op = old_path.get(method) if old_path else None
                new_op = methods.get(method)
                if not old_op and new_op:
                    continue  # New method is additive

                if old_op and new_op:
                    # Check removed parameters
                    old_params = {p['name']: p for p in old_op.get('parameters', [])}
                    new_params = {p['name']: p for p in new_op.get('parameters', [])}
                    removed = set(old_params) - set(new_params)
                    if removed:
                        breaking.append(f"{path} {method}: removed params {removed}")

                    # Check required parameters
                    for name, param in new_params.items():
                        if name in old_params:
                            old_required = old_params[name].get('required', False)
                            new_required = param.get('required', False)
                            if not old_required and new_required:
                                breaking.append(f"{path} {method}: {name} became required")
        return breaking

# Usage
old = json.load(open('spec-v1.json'))
new = json.load(open('spec-v2.json'))
tracker = VersionDiffTracker(old, new)
print(tracker.detect_breaking_changes())

# CI/CD version validation script
# .github/workflows/api-version-check.yml
name: API Version Check
on: pull_request
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check breaking changes
        run: |
          python scripts/detect-breaking-changes.py \
            --old spec-v1.json --new spec-v2.json
      - name: Validate version bump
        run: |
          python scripts/validate-version-bump.py \
            --old spec-v1.json --new spec-v2.json