ci: add openapi spec drift check against fixture schema

Author: mandarini

.github/workflows/openapi.yml

@@ -0,0 +1,44 @@
+name: OpenAPI
+
+on:
+  workflow_call:
+    secrets:
+      CACHIX_AUTH_TOKEN:
+        required: false
+  pull_request:
+    branches:
+      - main
+      - v[0-9]+
+    paths:
+      - "src/PostgREST/Response/OpenAPI.hs"
+      - "test/spec/fixtures/**"
+      - "test/openapi-drift-check.sh"
+      - ".github/workflows/openapi.yml"
+
+concurrency:
+  group: openapi-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  drift_check:
+    name: OpenAPI snapshot drift check
+    runs-on: ubuntu-24.04
+    defaults:
+      run:
+        shell: script -qec "bash --noprofile --norc -eo pipefail {0}"
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup Nix Environment
+        uses: ./.github/actions/setup-nix
+        with:
+          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
+          tools: withTools.pg-17.bin withTools.withPgrst.bin cabalTools.update.bin
+
+      - run: postgrest-cabal-update
+
+      - name: Verify OpenAPI snapshot is in sync with fixture schema
+        run: |
+          chmod +x test/openapi-drift-check.sh
+          postgrest-with-pg-17 --fixtures test/spec/fixtures/load.sql \
+            postgrest-with-pgrst test/openapi-drift-check.sh --check

test/openapi-drift-check.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Generates or verifies a snapshot of the OpenAPI (Swagger 2.0) document
+# emitted by PostgREST when run against the spec test fixture schema.
+#
+# Intended invocation (assumes nix devShell with withTools available):
+#
+#   # Regenerate the snapshot (write mode, default):
+#   postgrest-with-pg-17 --fixtures test/spec/fixtures/load.sql \
+#     postgrest-with-pgrst test/openapi-drift-check.sh
+#
+#   # Verify the snapshot is in sync (CI mode):
+#   postgrest-with-pg-17 --fixtures test/spec/fixtures/load.sql \
+#     postgrest-with-pgrst test/openapi-drift-check.sh --check
+#
+# The script expects PGRST_SERVER_UNIX_SOCKET to be set, which
+# postgrest-with-pgrst provides.
+
+set -euo pipefail
+
+MODE="${1:-write}"
+SNAPSHOT="test/spec/fixtures/openapi-snapshot.json"
+
+: "${PGRST_SERVER_UNIX_SOCKET:?PGRST_SERVER_UNIX_SOCKET is required; run this script via postgrest-with-pgrst}"
+
+TMPFILE="$(mktemp)"
+trap 'rm -f "$TMPFILE"' EXIT
+
+curl -sSf -H "Accept: application/openapi+json" \
+  --unix-socket "$PGRST_SERVER_UNIX_SOCKET" \
+  http://localhost/ \
+  | jq -S . > "$TMPFILE"
+
+case "$MODE" in
+  --check)
+    if ! diff -u "$SNAPSHOT" "$TMPFILE"; then
+      cat >&2 <<EOF
+::error::OpenAPI snapshot is out of date.
+
+To regenerate it, run from inside the project nix devShell:
+
+  postgrest-with-pg-17 --fixtures test/spec/fixtures/load.sql \\
+    postgrest-with-pgrst test/openapi-drift-check.sh
+
+Then commit the updated $SNAPSHOT.
+EOF
+      exit 1
+    fi
+    echo "OpenAPI snapshot is up to date."
+    ;;
+  write|"")
+    mv "$TMPFILE" "$SNAPSHOT"
+    trap - EXIT
+    echo "Wrote $SNAPSHOT"
+    ;;
+  *)
+    echo "Unknown mode: $MODE (expected --check or write)" >&2
+    exit 2
+    ;;
+esac