feat(api): add API versioning, response transforms, and OpenAPI docs

.github/workflows/api-docs.yml

@@ -0,0 +1,50 @@
+name: API Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/**/*.ts'
+      - 'scripts/generate-api-docs.js'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'docs/api/**'
+      - '.github/workflows/api-docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: api-docs-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Generate API Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+      - run: npm ci
+      - run: npm run docs:generate
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/site
+
+  deploy:
+    name: Deploy API Docs
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/ci.yml

@@ -89,6 +89,27 @@ jobs:
       - uses: actions/upload-artifact@v4
         with: { name: dist, path: dist/, retention-days: 1 }
 
+  api-docs:
+    name: API Documentation
+    runs-on: ubuntu-latest
+    needs: install
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '${{ env.NODE_VERSION }}', cache: 'npm' }
+      - uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: node-modules-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+      - run: npm run docs:generate
+      - name: Verify generated API docs are committed
+        run: git diff --exit-code -- openapi-spec.json docs/api/openapi-spec.json docs/api/examples.md docs/site
+      - uses: actions/upload-artifact@v4
+        with:
+          name: api-docs-site
+          path: docs/site/
+          retention-days: 7
+
   unit-tests:
     name: Unit Tests & Coverage
     runs-on: ubuntu-latest
@@ -180,7 +201,7 @@ jobs:
   ci-success:
     name: CI Passed
     runs-on: ubuntu-latest
-    needs: [install, lint, format, typecheck, build, unit-tests, e2e-tests]
+    needs: [install, lint, format, typecheck, build, api-docs, unit-tests, e2e-tests]
     if: always()
     steps:
       - name: Check all jobs passed

docs/api/README.md

@@ -27,6 +27,17 @@ Welcome to the comprehensive API documentation for the TeachLink platform. This
 **Interactive Documentation**: 
 - Swagger UI: http://localhost:3000/api/docs
 
+**Generated Artifacts**:
+- OpenAPI JSON: [openapi-spec.json](./openapi-spec.json)
+- Example requests/responses: [examples.md](./examples.md)
+- Static docs site source: [../site/index.html](../site/index.html)
+
+Regenerate all API documentation artifacts with:
+
+```bash
+npm run docs:generate
+```
+
 ## Authentication
 
 Most API endpoints require authentication using JWT (JSON Web Tokens).

docs/api/examples.md

@@ -0,0 +1,84 @@
+# API Examples
+
+This file is generated by `npm run docs:generate` from `scripts/generate-api-docs.js`.
+
+## Login
+
+```bash
+curl -X POST http://localhost:3000/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"learner@example.com","password":"Password123!"}'
+```
+
+```json
+{
+  "success": true,
+  "message": "Login successful",
+  "data": {
+    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "refreshToken": "refresh_01JZ0D4R8R2Y3R9H2W6E5R4T1P",
+    "user": {
+      "id": "2f4d8b5f-91d2-43a1-bd1e-877b4f97d7b9",
+      "email": "learner@example.com",
+      "firstName": "Ada",
+      "lastName": "Lovelace",
+      "role": "student",
+      "status": "active"
+    }
+  }
+}
+```
+
+## Create Course
+
+```bash
+curl -X POST http://localhost:3000/courses \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"JavaScript Foundations","description":"Learn modern JavaScript from first principles.","category":"programming","level":"beginner","price":3999}'
+```
+
+```json
+{
+  "success": true,
+  "message": "Course created",
+  "data": {
+    "id": "8e4fd4f8-d8f3-46b5-8786-6f7167a654f4",
+    "title": "JavaScript Foundations",
+    "description": "Learn modern JavaScript from first principles.",
+    "category": "programming",
+    "level": "beginner",
+    "price": 3999,
+    "status": "published"
+  }
+}
+```
+
+## Search Content
+
+```bash
+curl "http://localhost:3000/search?q=javascript%20basics&filters=%7B%22category%22%3A%22programming%22%7D"
+```
+
+```json
+{
+  "results": [
+    {
+      "id": "8e4fd4f8-d8f3-46b5-8786-6f7167a654f4",
+      "title": "JavaScript Foundations",
+      "description": "Learn modern JavaScript from first principles.",
+      "category": "programming",
+      "level": "beginner",
+      "price": 3999,
+      "status": "published"
+    }
+  ],
+  "total": 1,
+  "page": 1,
+  "limit": 20,
+  "filters": {
+    "category": "programming"
+  },
+  "query": "javascript basics"
+}
+```