feat(api-docs): automated OpenAPI spec generation from Zod schemas

.github/workflows/ci.yml

@@ -293,6 +293,26 @@ jobs:
         run: ls -la dist/
         continue-on-error: false
 
+      - name: Generate OpenAPI spec
+        run: npm run generate:spec
+        continue-on-error: false
+
+      - name: Validate OpenAPI spec against OpenAPI 3.0 standard
+        run: npm run validate:spec
+        continue-on-error: false
+
+      - name: Check that generated spec matches committed spec
+        run: npm run check:spec
+        continue-on-error: false
+
+      - name: Upload OpenAPI spec as build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: openapi-spec
+          path: docs/openapi.json
+          retention-days: 7
+          if-no-files-found: error
+
   # Docker build job - optional, only runs if secrets are configured
   # To enable: Add REGISTRY_USERNAME and REGISTRY_PASSWORD to repository secrets
   docker:

.github/workflows/openapi-spec.yml

@@ -0,0 +1,64 @@
+name: OpenAPI Spec Deployment
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/openapi/**'
+      - 'src/routes/**'
+      - 'src/controllers/**'
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  generate-and-upload:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+          cache: npm
+
+      - name: Verify package-lock.json exists
+        run: |
+          if [ ! -f package-lock.json ]; then
+            npm install --package-lock-only
+          fi
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate OpenAPI spec
+        run: npm run generate:spec
+
+      - name: Validate OpenAPI spec
+        run: npm run validate:spec
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.OPENAPI_S3_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.OPENAPI_S3_SECRET_ACCESS_KEY }}
+          aws-region: ${{ vars.OPENAPI_S3_REGION || 'us-east-1' }}
+
+      - name: Upload OpenAPI spec to S3
+        run: npm run upload:spec
+        env:
+          AWS_REGION: ${{ vars.OPENAPI_S3_REGION || 'us-east-1' }}
+          AWS_S3_BUCKET: ${{ secrets.OPENAPI_S3_BUCKET }}
+          AWS_ACCESS_KEY_ID: ${{ secrets.OPENAPI_S3_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.OPENAPI_S3_SECRET_ACCESS_KEY }}
+          OPENAPI_S3_KEY: ${{ vars.OPENAPI_S3_KEY || 'openapi.json' }}
+
+      - name: Invalidate CloudFront cache (if applicable)
+        if: env.CLOUDFRONT_DISTRIBUTION_ID != ''
+        uses: chetan/invalidate-cloudfront-action@v2
+        env:
+          DISTRIBUTION: ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }}
+          PATHS: "/openapi.json"

PR_DESCRIPTION.md

@@ -0,0 +1,36 @@
+# OpenAPI Spec Auto-Generation
+
+## Summary
+
+Automates the generation, validation, and deployment of the OpenAPI 3.0 specification for the ProxyPay API. The spec is generated from Zod schemas and route definitions during the CI build, eliminating manual maintenance and ensuring the documentation is always accurate and in sync with the implementation.
+
+## Changes
+
+### New Scripts
+- **`scripts/generate-openapi-spec.ts`** — Generates the OpenAPI 3.0.3 specification from Zod schemas and path registrations at build time, writing it to `docs/openapi.json`
+- **`scripts/upload-openapi-spec.ts`** — Uploads the generated spec to S3 for the Redoc-powered documentation portal
+
+### CI/CD Integration
+- **`ci.yml`** — Enhanced with three new steps in the build job:
+  1. `generate:spec` — Generate the spec from source
+  2. `validate:spec` — Validate against the OpenAPI 3.0 standard
+  3. `check:spec` — Fail the build if the generated spec differs from the committed spec, enforcing that developers commit updated spec files with their changes
+  4. Uploads the generated spec as a build artifact
+- **`openapi-spec.yml`** — New workflow that generates and uploads the spec to S3 on pushes to main and on releases, powering the Redoc documentation portal
+
+### npm Scripts
+- `generate:spec` — Generate the OpenAPI spec from Zod schemas
+- `validate:spec` — Validate the spec against OpenAPI 3.0 (via swagger-cli)
+- `check:spec` — Generate, validate, and diff — fails if committed spec is stale
+- `upload:spec` — Upload the spec to S3
+
+### Generated Artifact
+- **`docs/openapi.json`** — The committed OpenAPI spec, always kept in sync by the `check:spec` CI gate
+
+## Benefits
+- **Always accurate** — Spec is generated from the source of truth (Zod schemas), eliminating drift
+- **CI-enforced** — Build fails if the spec is not updated alongside code changes
+- **Self-documenting** — Developers see spec changes as part of their PR diff
+- **Portal-ready** — Spec is automatically deployed to S3 for Redoc documentation
+
+closes #111