CI Drift Detection

Detect discrepancies between committed OpenAPI specifications and live source code in CI.

Why Drift Detection Matters

API documentation is only useful if it accurately reflects what is deployed. Often, developers modify controller parameters or validation rules without updating the committed OpenAPI specification file, leading to broken client SDKs and outdated documentation.

Geni includes a dedicated drift detection command:

php artisan geni:check --path=openapi.json

How geni:check Works

When geni:check runs:

1. It regenerates the OpenAPI document in-memory by analyzing the current codebase.
2. It reads the committed specification file at --path.
3. It normalizes and canonicalizes both documents by recursively sorting object keys while preserving semantically significant array orders.
4. It compares the two specifications:
   • If they are identical, it outputs "OpenAPI specification at openapi.json is up to date." and exits with code 0.
   • If they differ, it prints a human-readable list of added, removed, or changed paths, methods, parameters, and schemas, and exits with code 1.

Adding to GitHub Actions

Add a drift check step to your GitHub Actions workflow:

.github/workflows/ci.yml

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'

      - name: Install Dependencies
        run: composer install --prefer-dist --no-interaction

      - name: Verify OpenAPI Specification Drift
        run: php artisan geni:check --path=openapi.json

If a pull request introduces changes to API routes or validation rules without re-running php artisan geni:export --path=openapi.json, the CI step fails and blocks the PR from merging.

Diagnostic Relativization

To ensure that specifications generated on different developer machines (or in CI containers) produce identical output without false drift, Geni automatically relativizes all absolute file paths before storing them in x-geni-unresolved extensions.