diff --git a/README.dev.md b/README.dev.md index ee20a85..a33e303 100644 --- a/README.dev.md +++ b/README.dev.md @@ -1,5 +1,24 @@ # Development Setup +## ⚠️ Wichtige Hinweise für Frontend-Entwickler + +### 🔴 BREAKING CHANGES - API-Umstrukturierung (November 2025) + +Im Rahmen der OpenAPI-Auto-Generation wurden **massive Änderungen** an der API-Struktur vorgenommen: + +- **Authentication**: Alle Admin-Endpoints benötigen jetzt Bearer Token +- **Route-Struktur**: Einige Pfade haben sich geändert (Single Source of Truth: `routeMappings.js`) +- **Error Handling**: Neue HTTP-Status-Codes (403 für Auth-Fehler) + +**📖 Siehe:** +- **`frontend/MIGRATION-GUIDE.md`** - Detaillierte Migrations-Anleitung für Frontend +- **`backend/src/routes/README.md`** - Vollständige API-Route-Dokumentation +- **`AUTHENTICATION.md`** - Auth-System-Setup und Verwendung + +**Geschätzter Migrations-Aufwand**: 2-3 Stunden + +--- + ## Schnellstart ### Starten (Development Environment) @@ -33,6 +52,15 @@ docker compose -f docker/dev/docker-compose.yml logs -f backend-dev ## API-Entwicklung +### ⚠️ BREAKING CHANGES - Frontend Migration erforderlich + +**Massive API-Änderungen im November 2025:** +- Bearer Token Authentication für alle Admin-Endpoints +- Route-Pfade umstrukturiert (siehe `routeMappings.js`) +- Neue Error-Response-Formate + +**📖 Frontend Migration Guide**: `frontend/MIGRATION-GUIDE.md` + ### Route-Struktur Die API verwendet eine **Single Source of Truth** für Route-Mappings: diff --git a/backend/TESTING.md b/backend/TESTING.md deleted file mode 100644 index b53930d..0000000 --- a/backend/TESTING.md +++ /dev/null @@ -1,297 +0,0 @@ -# API Testing Guide - -## 🎯 Testing-Strategie - -### 1. Smoke Tests (Aktuell) - -**Script:** `test-openapi-paths.js` - -**Was wird getestet:** -- ✅ Alle Pfade sind erreichbar -- ✅ Server antwortet -- ❌ Keine Schema-Validierung -- ❌ Keine Auth-Tests -- ❌ Keine Request Bodies - -**Verwendung:** -```bash -npm run test-openapi -``` - -**Zweck:** Schneller Check ob alle Routen mounted sind. - ---- - -## 🔧 Empfohlene Testing-Tools - -### Option 1: Dredd (Contract Testing) ⭐ EMPFOHLEN - -**Installation:** -```bash -npm install --save-dev dredd -``` - -**Setup:** -```bash -# dredd.yml erstellen -cat > dredd.yml << EOF -color: true -dry-run: false -hookfiles: null -language: nodejs -require: null -server: npm start -server-wait: 3 -init: false -custom: {} -names: false -only: [] -reporter: [] -output: [] -header: [] -sorted: false -user: null -inline-errors: false -details: false -method: [] -loglevel: warning -path: [] -blueprint: docs/openapi.json -endpoint: http://localhost:5000 -EOF -``` - -**Ausführen:** -```bash -npx dredd -``` - -**Vorteile:** -- ✅ Validiert Responses gegen OpenAPI-Schema -- ✅ Testet alle HTTP-Methoden -- ✅ Prüft Request/Response Bodies -- ✅ Unterstützt Hooks für Auth - ---- - -### Option 2: Postman + Newman - -**Setup:** -1. OpenAPI importieren: - - Öffne Postman - - File → Import → `backend/docs/openapi.json` - -2. Collection generieren lassen - -3. Tests hinzufügen (automatisch oder manuell) - -4. Export als Collection - -**CLI-Tests:** -```bash -npm install --save-dev newman -npx newman run postman_collection.json -``` - -**Vorteile:** -- ✅ GUI für manuelles Testen -- ✅ Automatische Test-Generierung -- ✅ CI/CD Integration -- ✅ Environment Variables - ---- - -### Option 3: Prism (Mock + Validate) - -**Installation:** -```bash -npm install --save-dev @stoplight/prism-cli -``` - -**Mock Server starten:** -```bash -npx prism mock docs/openapi.json -# Server läuft auf http://localhost:4010 -``` - -**Validierung:** -```bash -npx prism validate docs/openapi.json -``` - -**Vorteile:** -- ✅ Mock Server für Frontend-Entwicklung -- ✅ Schema-Validierung -- ✅ Contract Testing -- ✅ Keine echte API nötig - ---- - -### Option 4: Jest + Supertest (Unit/Integration Tests) - -**Installation:** -```bash -npm install --save-dev jest supertest jest-openapi -``` - -**Beispiel Test:** -```javascript -// tests/api/groups.test.js -const request = require('supertest'); -const jestOpenAPI = require('jest-openapi'); -const app = require('../../src/server'); - -// Load OpenAPI spec -jestOpenAPI(require('../../docs/openapi.json')); - -describe('Groups API', () => { - it('GET /api/groups should return valid response', async () => { - const response = await request(app) - .get('/api/groups') - .expect(200); - - // Validate against OpenAPI schema - expect(response).toSatisfyApiSpec(); - - // Custom assertions - expect(response.body).toHaveProperty('groups'); - expect(Array.isArray(response.body.groups)).toBe(true); - }); - - it('GET /api/groups/:groupId should return 404 for invalid ID', async () => { - const response = await request(app) - .get('/api/groups/invalid-id') - .expect(404); - - expect(response).toSatisfyApiSpec(); - }); -}); -``` - -**package.json:** -```json -{ - "scripts": { - "test": "jest", - "test:watch": "jest --watch", - "test:coverage": "jest --coverage" - } -} -``` - -**Vorteile:** -- ✅ Vollständige Integration Tests -- ✅ Schema-Validierung mit jest-openapi -- ✅ Code Coverage -- ✅ CI/CD Integration -- ✅ Watch Mode für TDD - ---- - -## 📊 Vergleich - -| Tool | Setup | Schema Validation | Auth Support | CI/CD | Best For | -|------|-------|-------------------|--------------|-------|----------| -| **test-openapi-paths.js** | ✅ Fertig | ❌ | ❌ | ✅ | Quick smoke test | -| **Dredd** | ⚠️ Mittel | ✅ | ✅ | ✅ | Contract testing | -| **Postman/Newman** | ⚠️ Mittel | ✅ | ✅ | ✅ | Manual + automated | -| **Prism** | ✅ Easy | ✅ | ⚠️ | ✅ | Mock + validate | -| **Jest + Supertest** | ⚠️ Komplex | ✅ | ✅ | ✅ | Full testing suite | - ---- - -## 🚀 Empfehlung für dieses Projekt - -### Phase 1: Quick Wins (Jetzt) -```bash -# 1. Behalte aktuelles Smoke-Test Script -npm run test-openapi - -# 2. Installiere Prism für Validierung -npm install --save-dev @stoplight/prism-cli - -# 3. Validiere OpenAPI Spec -npm run validate-openapi # (siehe unten) -``` - -### Phase 2: Contract Testing (Später) -```bash -# 1. Installiere Dredd -npm install --save-dev dredd - -# 2. Erstelle dredd.yml (siehe oben) - -# 3. Schreibe Hooks für Auth -# tests/dredd-hooks.js - -# 4. Führe aus -npm run test:contract -``` - -### Phase 3: Full Testing Suite (Optional) -```bash -# Jest + Supertest + jest-openapi -npm install --save-dev jest supertest jest-openapi @types/jest - -# Schreibe Integration Tests in tests/ -npm run test -``` - ---- - -## 📝 Neue NPM Scripts - -Füge zu `package.json` hinzu: - -```json -{ - "scripts": { - "test-openapi": "node test-openapi-paths.js", - "validate-openapi": "prism validate docs/openapi.json", - "test:contract": "dredd", - "test": "jest", - "test:watch": "jest --watch" - } -} -``` - ---- - -## 🔗 Swagger-eigene Test-Tools - -**Swagger Inspector:** -- Online: https://inspector.swagger.io/ -- Import `openapi.json` -- Manuelles Testen in GUI -- Kann Test-Collections exportieren - -**Swagger Codegen:** -```bash -# Generiert Client-Code + Tests -npx @openapitools/openapi-generator-cli generate \ - -i docs/openapi.json \ - -g javascript \ - -o generated-client -``` - -**Swagger UI "Try it out":** -- Bereits aktiv unter http://localhost:5000/api/docs -- Manuelles Testing direkt in Browser -- ✅ Einfachstes Tool für Quick Tests - ---- - -## ✅ Fazit - -**Aktuell:** `test-openapi-paths.js` ist OK für Smoke Tests. - -**Nächster Schritt:** -1. Installiere **Prism** für Schema-Validierung -2. Später: **Dredd** für Contract Testing -3. Optional: **Jest** für vollständige Test-Suite - -**Best Practice:** Kombiniere mehrere Tools: -- Prism für Schema-Validierung -- Dredd für Contract Testing -- Jest für Unit/Integration Tests -- Swagger UI für manuelles Testing diff --git a/backend/test-openapi-paths.js b/backend/test-openapi-paths.js deleted file mode 100644 index 6fcaf04..0000000 --- a/backend/test-openapi-paths.js +++ /dev/null @@ -1,64 +0,0 @@ -/** - * OpenAPI Path Validator - * - * Basic smoke test to verify all OpenAPI paths are reachable. - * Does NOT replace proper API testing! - * - * For comprehensive testing, consider: - * - Dredd (npm install -g dredd) - Contract testing against OpenAPI spec - * - Postman/Newman - Import openapi.json and run automated tests - * - Prism (npm install -g @stoplight/prism-cli) - Mock server + validation - * - Jest/Supertest - Full integration tests with schema validation - * - * This script only checks if paths respond (basic reachability check). - */ - -const fs = require('fs'); -const path = require('path'); - -// Read generated openapi.json -const specPath = path.join(__dirname, 'docs', 'openapi.json'); -const spec = JSON.parse(fs.readFileSync(specPath, 'utf8')); - -const baseUrl = 'http://localhost:5000'; -const paths = Object.keys(spec.paths || {}); - -console.log(`🔍 Testing ${paths.length} paths from openapi.json against ${baseUrl}\n`); - -async function testPath(path, methods) { - const method = Object.keys(methods)[0]; // take first method (usually GET) - const url = `${baseUrl}${path}`; - - return new Promise((resolve) => { - const http = require('http'); - const req = http.request(url, { method: method.toUpperCase() }, (res) => { - const status = res.statusCode; - const statusEmoji = status === 200 ? '✅' : status === 404 ? '❌' : '⚠️'; - console.log(`${statusEmoji} ${method.toUpperCase()} ${path} → ${status}`); - resolve({ path, status, ok: status === 200 }); - }); - req.on('error', (err) => { - console.log(`💥 ${method.toUpperCase()} ${path} → ERROR: ${err.message}`); - resolve({ path, status: 'ERROR', ok: false }); - }); - req.end(); - }); -} - -(async () => { - const results = []; - for (const p of paths) { - const result = await testPath(p, spec.paths[p]); - results.push(result); - } - - const failed = results.filter(r => !r.ok); - console.log(`\n📊 Summary: ${results.length} paths tested, ${failed.length} failed\n`); - - if (failed.length > 0) { - console.log('❌ Failed paths (likely missing route prefixes):'); - failed.forEach(f => console.log(` ${f.path} → ${f.status}`)); - console.log('\n💡 Hint: Generator scanned route files without mount prefixes.'); - console.log(' Check backend/src/routes/index.js for app.use() calls with prefixes like /api/admin'); - } -})();