Generate OpenAPI spec from zod schemas + CI drift check

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - name: Typecheck / build
+        run: npm run build
+
+      - name: Unit tests
+        run: npm test
+
+      # Fails if swagger.yaml drifted from the zod request schemas.
+      # Regenerate locally with `npm run openapi:generate` and commit.
+      - name: OpenAPI spec is in sync
+        run: npm run openapi:check

README.md

@@ -682,6 +682,22 @@ curl -X POST https://deepscrapper.ai/api/crawl \
 
 ## API Usage
 
+### OpenAPI specification
+
+Every endpoint is described in [`swagger.yaml`](swagger.yaml) (OpenAPI 3.0) — paste it into
+[editor.swagger.io](https://editor.swagger.io/), or generate a client with `openapi-generator`.
+
+The file is **generated from the zod request schemas** in `src/api/schemas`, which are the same
+schemas the routes validate with — so the documented options can't drift from what the API
+actually accepts:
+
+```bash
+npm run openapi:generate   # rewrite swagger.yaml after changing a schema
+npm run openapi:check      # verify it's in sync (CI runs this)
+```
+
+CI also fails if an endpoint is added without appearing in the spec, so coverage stays complete.
+
 ### Basic Scraping
 
 ```bash

package.json

@@ -8,6 +8,8 @@
     "dev": "ts-node src/index.ts",
     "build": "tsc",
     "test": "jest",
+    "openapi:generate": "ts-node -T src/api/openapi/generate.ts",
+    "openapi:check": "ts-node -T src/api/openapi/generate.ts --check",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",
     "clean": "rm -rf dist cache",
@@ -33,13 +35,13 @@
     "cors": "^2.8.5",
     "diff": "^5.2.0",
     "dotenv": "^16.4.7",
-    "mammoth": "^1.8.0",
     "express": "^4.18.2",
     "express-rate-limit": "^7.4.1",
     "express-validator": "^7.2.1",
     "helmet": "^7.1.0",
     "ioredis": "^5.6.0",
     "ipaddr.js": "^2.2.0",
+    "mammoth": "^1.8.0",
     "morgan": "^1.10.0",
     "openai": "^4.89.1",
     "pako": "^2.1.0",
@@ -56,15 +58,17 @@
     "zod": "^3.22.4"
   },
   "devDependencies": {
+    "@asteasolutions/zod-to-openapi": "^7.3.4",
     "@types/archiver": "^6.0.3",
     "@types/cors": "^2.8.17",
     "@types/diff": "^5.2.1",
     "@types/express": "^4.17.21",
-    "@types/pdf-parse": "^1.1.4",
     "@types/jest": "^29.5.10",
+    "@types/js-yaml": "^4.0.9",
     "@types/morgan": "^1.9.9",
     "@types/node": "^20.10.0",
     "@types/pako": "^2.0.3",
+    "@types/pdf-parse": "^1.1.4",
     "@types/turndown": "^5.0.4",
     "@types/user-agents": "^1.0.4",
     "@types/uuid": "^10.0.0",
@@ -73,6 +77,7 @@
     "@typescript-eslint/parser": "^8.31.0",
     "eslint": "^9.25.1",
     "jest": "^29.7.0",
+    "js-yaml": "^5.2.1",
     "nodemon": "^3.1.9",
     "ts-jest": "^29.1.1",
     "ts-node": "^10.9.2",