feat: commit OpenAPI spec with CI freshness check (#220)

Author: declan-scale

.github/workflows/ci.yml

@@ -167,12 +167,52 @@ jobs:
           exit 1
         fi
 
+  openapi-spec:
+    name: "Verify OpenAPI spec is up to date"
+    runs-on: ubuntu-latest
+    needs: changes
+    if: needs.changes.outputs.agentex == 'true'
+    timeout-minutes: 10
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "0.7.3"
+        enable-cache: true
+
+    - name: Install dependencies
+      working-directory: ./agentex
+      run: uv sync
+
+    - name: Regenerate OpenAPI spec
+      working-directory: ./agentex
+      run: uv run python scripts/generate_openapi_spec.py --output openapi.yaml
+
+    - name: Verify committed spec matches generated spec
+      working-directory: ./agentex
+      run: |
+        if ! git diff --exit-code openapi.yaml; then
+          echo "❌ The committed openapi.yaml is out of date."
+          echo "Run 'uv run python scripts/generate_openapi_spec.py --output openapi.yaml' from agentex/ and commit the result."
+          exit 1
+        fi
+        echo "✅ openapi.yaml is up to date"
+
   # This job is used as a required status check for branch protection
   # It will pass if the conditional jobs either passed or were skipped
   ci-status:
     name: "CI Status Check"
     runs-on: ubuntu-latest
-    needs: [changes, test, docs]
+    needs: [changes, test, docs, openapi-spec]
     if: always()
     steps:
       - name: Check CI status
@@ -191,7 +231,12 @@ jobs:
               echo "❌ Documentation build failed"
               exit 1
             fi
-            
+
+            if [ "${{ needs.openapi-spec.result }}" != "success" ]; then
+              echo "❌ OpenAPI spec freshness check failed"
+              exit 1
+            fi
+
             echo "✅ All checks passed"
           else
             echo "No agentex changes detected - skipping tests and docs"

.pre-commit-config.yaml

@@ -18,3 +18,10 @@ repos:
         files: ^agentex-ui/.*\.(ts|tsx|js|jsx)$
         pass_filenames: true
 
+      - id: agentex-openapi-spec
+        name: Regenerate AgentEx OpenAPI spec
+        entry: bash -c 'cd agentex && make gen-openapi && git add openapi.yaml'
+        language: system
+        files: ^agentex/(src/.*|scripts/generate_openapi_spec\.py)$
+        pass_filenames: false
+

agentex/Makefile

@@ -68,6 +68,13 @@ migration: ## Create a new migration (usage: make migration NAME="migration_name
 apply-migrations: ## Apply database migrations
 	cd database/migrations && alembic upgrade head
 
+#
+# OpenAPI Spec
+#
+
+gen-openapi: ## Regenerate openapi.yaml from the FastAPI app
+	@uv run --frozen python scripts/generate_openapi_spec.py --output openapi.yaml
+
 #
 # Documentation
 #