Project-Image-Uploader/docs/FEATURE_PLAN-autogen-openapi.md

Feature Plan: Autogenerierte OpenAPI / Swagger Spec + API Restructuring

Branch: feature/autogen-openapi
Datum: 16. November 2025
Status: ✅ Complete - Auto-generation active, Single Source of Truth established

🎯 Hauptziele

1. ✅ OpenAPI Auto-Generation: Swagger Spec wird automatisch aus Route-Definitionen generiert
2. ✅ Konsistente API-Struktur: Klare, REST-konforme API-Organisation für einfache KI-Navigation
3. ✅ Single Source of Truth: routeMappings.js als zentrale Route-Konfiguration
4. ✅ Developer Experience: Swagger UI unter /api/docs (dev-only)
5. ✅ Test Coverage: 45 automatisierte Tests, 100% passing
6. ✅ API Security: Bearer Token Authentication für Admin-Endpoints

---

📊 API-Struktur (Ziel)

Design-Prinzipien

• Prefix = Zugriffsebene: Struktur basiert auf Authentifizierung/Autorisierung
• REST-konform: Standard HTTP Methoden (GET, POST, PUT, PATCH, DELETE)
• KI-freundlich: Klare Hierarchie, vorhersagbare Patterns
• Konsistent: Alle Routen folgen dem gleichen Muster

Routing-Schema

/api/upload              (öffentlich - Upload-Funktionen)
/api/groups              (öffentlich - Slideshow-Anzeige)
/api/manage/:token/*     (token-basiert - User-Verwaltung)
/api/admin/*             (geschützt - Moderation)
/api/system/*            (intern - Wartung)

Detaillierte Endpunkte

📤 Public API

POST   /api/upload              - Single file upload
POST   /api/upload/batch        - Batch upload
GET    /api/groups              - List approved slideshows
GET    /api/groups/:groupId     - View specific slideshow

🔑 Management API

Token-basierter Zugriff für Slideshow-Ersteller:

GET    /api/manage/:token                    - Get slideshow info
PUT    /api/manage/:token/consents           - Update consents
PUT    /api/manage/:token/metadata           - Update metadata
PUT    /api/manage/:token/images/descriptions - Update image descriptions
POST   /api/manage/:token/images             - Add images
DELETE /api/manage/:token/images/:imageId    - Delete image
DELETE /api/manage/:token                    - Delete slideshow

👮 Admin API

Geschützte Moderation- und Management-Funktionen:

# Moderation
GET    /api/admin/moderation/groups           - List pending slideshows
GET    /api/admin/moderation/groups/:id       - Get slideshow details
PATCH  /api/admin/groups/:id/approve          - Approve slideshow
PATCH  /api/admin/groups/:id                  - Edit slideshow
DELETE /api/admin/groups/:id/images/:imageId  - Delete single image
PATCH  /api/admin/groups/:id/images/batch-description
PUT    /api/admin/groups/:id/reorder          - Reorder images

# Logs & Monitoring
GET    /api/admin/deletion-log                - Recent deletions
GET    /api/admin/deletion-log/stats          - Deletion statistics
GET    /api/admin/management-audit            - Audit log
GET    /api/admin/rate-limiter/stats          - Rate limiter stats

# Cleanup
POST   /api/admin/cleanup/trigger             - Trigger cleanup
GET    /api/admin/cleanup/preview             - Preview cleanup targets

# Consents & Social Media
GET    /api/admin/consents/export             - Export consents (CSV)
GET    /api/admin/social-media/platforms      - List platforms

⚙️ System API

Interne System-Operationen:

GET    /api/system/migration/status   - Migration status
POST   /api/system/migration/migrate  - Run migration
POST   /api/system/migration/rollback - Rollback migration
GET    /api/system/migration/health   - Health check

---

🔧 Technische Implementierung

Komponenten

• swagger-autogen (v6.2.8): OpenAPI 3.0 Generation
• swagger-ui-express (v4.6.3): Interactive API docs
• Custom Generator: src/generate-openapi.js

Generator-Logik

// Pro Router-Datei einzeln scannen + Mount-Prefix anwenden
for each routerMapping {
  swaggerAutogen(tempFile, [routeFile], { basePath: prefix })
  merge paths with prefix into final spec
}

Single Source of Truth

1. Router-Files (src/routes/*.js): Enthalten nur relative Pfade
2. Mount-Konfiguration (src/routes/index.js): Definiert Prefixes
3. OpenAPI Generation: generate-openapi.js liest beide und merged

---

📚 Für KI-Nutzung

API-Hierarchie verstehen

/api/*                    ← Alle API-Endpoints
  ├─ /upload, /groups     ← Öffentlich
  ├─ /manage/:token/*     ← Token-basiert
  ├─ /admin/*             ← Geschützt
  └─ /system/*            ← Intern

Neue Route hinzufügen

# 1. Route in passender Datei hinzufügen (z.B. admin.js)
router.get('/new-endpoint', ...)

# 2. In routeMappings.js registrieren (falls neue Datei)
{ router: 'newRoute', prefix: '/api/admin', file: 'newRoute.js' }

# 3. OpenAPI wird automatisch beim Backend-Start generiert
npm run dev

# 4. Tests schreiben: tests/api/newRoute.test.js
npm test

# 5. Swagger UI: http://localhost:5001/api/docs

---

✅ Implementierungsstatus (November 16, 2025)

Completed Features

✅ Single Source of Truth: routeMappings.js als zentrale Route-Konfiguration
✅ Auto-Generation: OpenAPI-Spec automatisch beim Backend-Start
✅ Authentication: Bearer Token für Admin-Endpoints
✅ Test Suite: 45 automatisierte Tests (100% passing)
✅ Documentation: routes/README.md + AUTHENTICATION.md
✅ Route Order Fix: Express routing order documented & fixed

Known Issues (Resolved)

✅ Express Route Order: Consent router now mounted before admin router
✅ Test Permissions: Tests use /tmp/ for uploads
✅ SQLite Async: Connection properly promisified

---

⏱️ Aufwandsschätzung (Final)

Phase	Zeit	Status
MVP OpenAPI Generation	2h	✅ Done
API Restructuring	8h	✅ Done
Authentication System	4h	✅ Done
Test Suite	6h	✅ Done
Documentation	2h	✅ Done
Total	22h	100%

---

🚀 Frontend Migration Guide

Required Changes:

1. Add Bearer Token: All /api/admin/* calls need Authorization: Bearer <token> header
2. Verify Paths: Check against routeMappings.js (consent: /api/admin/groups/by-consent)
3. Handle 403: Add error handling for missing authentication
4. Environment: Add REACT_APP_ADMIN_API_KEY to .env

See AUTHENTICATION.md for complete setup guide

---

Erstellt: 16. November 2025
Aktualisiert: 16. November 2025
Status: ✅ Production Ready