docs: add Swagger/OpenAPI documentation for DEBUG-API

- Install flasgger dependency (0.9.7.1)
- Initialize Swagger in app.py with config
- Add YAML docstring with OpenAPI spec to debug_management()
- Create comprehensive debug-api-swagger.md guide
- Create debug-api-cheatsheet.md for quick reference
- Swagger UI available at /swagger endpoint
- OpenAPI JSON at /openapi.json

admin_api.py

@@ -374,18 +374,67 @@ def get_active_takeovers():
 def debug_management():
     """
     Debug-Management Endpoint für Logs und Datenbank-Bereinigung
-
+    ---
-    Authentifizierung via:
+    tags:
-    1. DEBUG_TOKEN Header: X-Debug-Token: <token>
+      - Debug
-    2. Oder Admin JWT Token
+    parameters:
-
+      - name: action
-    Actions:
+        in: query
-    - view-logs: Zeigt letzte 100 Zeilen der Logs
+        type: string
-    - clear-logs: Löscht alle Logs
+        required: true
-    - delete-email: Entfernt User und alle zugehörigen Daten
+        enum:
-      Parameter: ?email=test@example.com
+          - view-logs
-    - delete-token: Entfernt Magic Link Tokens für Email
+          - clear-logs
-      Parameter: ?email=test@example.com
+          - list-users
+          - delete-email
+          - delete-token
+          - info
+        description: Welche Aktion soll ausgeführt werden?
+      - name: email
+        in: query
+        type: string
+        required: false
+        description: Email-Adresse des Users (erforderlich für delete-email und delete-token)
+      - name: X-Debug-Token
+        in: header
+        type: string
+        required: false
+        description: Debug-Token alternativ zu JWT-Authentication
+    security:
+      - jwt: []
+      - debug_token: []
+    responses:
+      200:
+        description: Erfolgreich ausgeführt
+        schema:
+          type: object
+          properties:
+            action:
+              type: string
+              description: Die ausgeführte Aktion
+            message:
+              type: string
+              description: Rückmeldung
+            logs:
+              type: string
+              description: Log-Inhalte (nur bei view-logs)
+            users:
+              type: array
+              description: Liste der User (nur bei list-users)
+            tokens_deleted:
+              type: integer
+              description: Anzahl gelöschter Tokens
+      400:
+        description: Ungültige Parameter
+        schema:
+          type: object
+          properties:
+            error:
+              type: string
+      403:
+        description: Authentifizierung erforderlich
+      404:
+        description: User oder Ressource nicht gefunden
     """
     # Authentifizierung prüfen
     debug_token = current_app.config.get('DEBUG_TOKEN')

app.py

@@ -2,6 +2,7 @@ from flask import Flask, render_template, redirect, url_for, jsonify
 from flask_login import LoginManager, login_required, current_user
 from flask_jwt_extended import JWTManager
 from flask_cors import CORS
+from flasgger import Swagger
 from sqlalchemy import text
 from models import db, User, AdminTakeoverSession
 from auth import auth_bp
@@ -33,6 +34,30 @@ CORS(app, resources={
 # JWT initialisieren
 jwt = JWTManager(app)
 
+# Swagger/OpenAPI initialisieren
+swagger_config = {
+    "headers": [],
+    "specs": [
+        {
+            "endpoint": 'openapi',
+            "route": '/openapi.json',
+            "rule_filter": lambda rule: True,
+            "model_filter": lambda tag: True,
+        }
+    ],
+    "static_url_path": "/flasgger_static",
+    "swagger_ui": True,
+    "specs_route": "/swagger",
+    "title": "Container Spawner API",
+    "description": "API für Container-Spawner mit Admin-Debug-Endpoints",
+    "version": "2.0.0",
+    "termsOfService": "",
+    "contact": {
+        "name": "API Support"
+    }
+}
+swagger = Swagger(app, config=swagger_config)
+
 @jwt.token_in_blocklist_loader
 def check_if_token_in_blocklist(jwt_header, jwt_payload):
     return check_if_token_revoked(jwt_header, jwt_payload)

docs/guides/debug-api-cheatsheet.md

@@ -0,0 +1,192 @@
+# DEBUG-API Quick Reference (Cheatsheet)
+
+## 🚀 Schnelle Befehle
+
+### Swagger UI öffnen
+```bash
+http://localhost:5000/swagger
+```
+
+### View Logs
+```bash
+curl -H "X-Debug-Token: SECRET" \
+  "http://localhost:5000/api/admin/debug?action=view-logs" | jq '.logs'
+```
+
+### List Users
+```bash
+curl -H "X-Debug-Token: SECRET" \
+  "http://localhost:5000/api/admin/debug?action=list-users" | jq '.users'
+```
+
+### Delete User (⚠️ Warning!)
+```bash
+curl -H "X-Debug-Token: SECRET" \
+  "http://localhost:5000/api/admin/debug?action=delete-email&email=test@example.com"
+```
+
+### Delete Tokens
+```bash
+curl -H "X-Debug-Token: SECRET" \
+  "http://localhost:5000/api/admin/debug?action=delete-token&email=spam@example.com"
+```
+
+### Clear Logs
+```bash
+curl -H "X-Debug-Token: SECRET" \
+  "http://localhost:5000/api/admin/debug?action=clear-logs"
+```
+
+---
+
+## 🔐 Authentifizierung
+
+### Methode 1: DEBUG_TOKEN
+```bash
+curl -H "X-Debug-Token: your-secret-token" \
+  "http://localhost:5000/api/admin/debug?action=list-users"
+```
+
+### Methode 2: JWT Token
+```bash
+curl -H "Authorization: Bearer $JWT_TOKEN" \
+  "http://localhost:5000/api/admin/debug?action=list-users"
+```
+
+---
+
+## 📋 Alle Actions
+
+| Action | Methode | Parameter | Beschreibung |
+|--------|---------|-----------|--------------|
+| `view-logs` | GET | - | Zeigt letzte 100 Log-Zeilen |
+| `clear-logs` | GET/POST | - | Löscht alle Logs |
+| `list-users` | GET | - | Listet alle User auf |
+| `delete-email` | GET/POST | `email=...` | Löscht User + Daten |
+| `delete-token` | GET/POST | `email=...` | Löscht Tokens für User |
+| `info` | GET | - | Zeigt diese Hilfe |
+
+---
+
+## 🎯 Häufige Use-Cases
+
+### Use-Case 1: User hat zu viele Magic Links (Spam)
+```bash
+curl -H "X-Debug-Token: $DEBUG_TOKEN" \
+  "http://localhost:5000/api/admin/debug?action=delete-token&email=user@example.com"
+```
+
+### Use-Case 2: User-Container ist kaputt, User löschen + neu starten
+```bash
+# 1. Alten User löschen
+curl -H "X-Debug-Token: $DEBUG_TOKEN" \
+  "http://localhost:5000/api/admin/debug?action=delete-email&email=user@example.com"
+
+# 2. User kann sich neu registrieren
+```
+
+### Use-Case 3: Logs einmal wöchentlich leeren
+```bash
+# Cronjob
+0 0 * * 0 curl -H "X-Debug-Token: $DEBUG_TOKEN" \
+  "http://localhost:5000/api/admin/debug?action=clear-logs"
+```
+
+### Use-Case 4: Alle User sehen
+```bash
+curl -H "X-Debug-Token: $DEBUG_TOKEN" \
+  "http://localhost:5000/api/admin/debug?action=list-users" | \
+  jq -r '.users[] | "\(.email) (\(.state))"'
+
+# Output:
+# admin@example.com (active)
+# user1@example.com (verified)
+# user2@example.com (registered)
+```
+
+---
+
+## ⚡ Pro-Tipps
+
+### Shell Alias für schnellere Befehle
+```bash
+# In ~/.bashrc oder ~/.zshrc hinzufügen:
+alias spawner-logs='curl -H "X-Debug-Token: $DEBUG_TOKEN" "http://localhost:5000/api/admin/debug?action=view-logs" | jq'
+alias spawner-users='curl -H "X-Debug-Token: $DEBUG_TOKEN" "http://localhost:5000/api/admin/debug?action=list-users" | jq'
+```
+
+### Dann nutzen:
+```bash
+spawner-logs     # Zeigt Logs
+spawner-users    # Zeigt User
+```
+
+### JSON Output formatieren
+```bash
+# Pretty-print
+curl ... | jq '.'
+
+# Nur spezifische Felder
+curl ... | jq '.users[] | {email, state, created_at}'
+
+# Filter
+curl ... | jq '.users[] | select(.is_blocked == true)'
+```
+
+### Logs in Echtzeit verfolgen
+```bash
+docker-compose logs -f spawner | grep -i "error\|warning"
+```
+
+---
+
+## 🔒 Sicherheits-Checkliste
+
+- [ ] DEBUG_TOKEN ist mindestens 32 Zeichen lang
+- [ ] DEBUG_TOKEN ist in `.env` und NICHT im Git
+- [ ] DEBUG-API nur intern/localhost erreichbar (nicht exponiert)
+- [ ] Regelmäßig Logs leeren (Privacy)
+- [ ] User-Löschungen werden geloggt
+- [ ] Nur Admins haben Zugriff auf DEBUG_TOKEN
+
+---
+
+## 🆘 Schnelle Hilfe
+
+**Swagger zeigt 404?**
+```bash
+docker-compose restart spawner
+docker exec spawner pip install flasgger==0.9.7.1
+```
+
+**DEBUG_TOKEN funktioniert nicht?**
+```bash
+# Prüfe ob gesetzt
+docker exec spawner cat /app/.env | grep DEBUG_TOKEN
+
+# Falls leer, neu setzen
+docker-compose down
+nano .env  # DEBUG_TOKEN hinzufügen
+docker-compose up -d
+```
+
+**Kann User nicht löschen?**
+```bash
+# Prüfe Logs
+docker-compose logs spawner | grep -i "error"
+
+# User manuell prüfen
+docker exec spawner python3 -c "
+from app import app, db
+from models import User
+with app.app_context():
+    user = User.query.filter_by(email='test@example.com').first()
+    print(user)
+"
+```
+
+---
+
+**Stand:** 2026-02-02
+**Flasgger:** 0.9.7.1
+**OpenAPI:** 3.0.0

docs/guides/debug-api-swagger.md

@@ -0,0 +1,457 @@
+# DEBUG-API Swagger/OpenAPI Dokumentation
+
+**Status:** ✅ Vollständig dokumentiert mit Flasgger
+**Zugänglich unter:** `http://localhost:5000/swagger` (UI) oder `http://localhost:5000/openapi.json` (JSON)
+
+---
+
+## 🚀 Schnellstart
+
+### Swagger UI öffnen:
+```
+http://localhost:5000/swagger
+```
+
+### OpenAPI JSON herunterladen:
+```
+http://localhost:5000/openapi.json
+```
+
+---
+
+## 📚 DEBUG-API Endpoints
+
+### 1️⃣ VIEW-LOGS: Letzte 100 Log-Zeilen anzeigen
+
+**Endpoint:** `GET /api/admin/debug?action=view-logs`
+
+**Authentifizierung:**
+```bash
+# Option 1: Mit DEBUG_TOKEN Header
+curl -H "X-Debug-Token: your-secret-token" \
+  "http://localhost:5000/api/admin/debug?action=view-logs"
+
+# Option 2: Mit Admin JWT Token
+curl -H "Authorization: Bearer $JWT_TOKEN" \
+  "http://localhost:5000/api/admin/debug?action=view-logs"
+```
+
+**Response (200 OK):**
+```json
+{
+  "action": "view-logs",
+  "source": "Flask Log File",
+  "total_lines": 1234,
+  "displayed_lines": 100,
+  "logs": "[2026-02-02 17:30:45] User test@example.com registered..."
+}
+```
+
+**Response (404 Not Found):**
+```json
+{
+  "error": "Log-Datei nicht gefunden: /app/logs/spawner.log"
+}
+```
+
+---
+
+### 2️⃣ CLEAR-LOGS: Log-Datei leeren
+
+**Endpoint:** `GET|POST /api/admin/debug?action=clear-logs`
+
+**Authentifizierung:** (wie oben)
+
+**Response (200 OK):**
+```json
+{
+  "action": "clear-logs",
+  "message": "Log-Datei wurde geleert",
+  "log_file": "/app/logs/spawner.log"
+}
+```
+
+---
+
+### 3️⃣ LIST-USERS: Alle registrierten User auflisten
+
+**Endpoint:** `GET /api/admin/debug?action=list-users`
+
+**Authentifizierung:** (wie oben)
+
+**Response (200 OK):**
+```json
+{
+  "action": "list-users",
+  "users": [
+    {
+      "id": 1,
+      "email": "admin@example.com",
+      "slug": "u-a1b2c3d4",
+      "state": "active",
+      "is_admin": true,
+      "is_blocked": false,
+      "created_at": "2026-01-15T10:30:00",
+      "last_used": "2026-02-02T17:30:00"
+    },
+    {
+      "id": 2,
+      "email": "user@example.com",
+      "slug": "u-e5f6g7h8",
+      "state": "verified",
+      "is_admin": false,
+      "is_blocked": false,
+      "created_at": "2026-02-01T14:00:00",
+      "last_used": null
+    }
+  ],
+  "total": 2
+}
+```
+
+---
+
+### 4️⃣ DELETE-EMAIL: User und alle Daten löschen
+
+**Endpoint:** `GET|POST /api/admin/debug?action=delete-email&email=test@example.com`
+
+⚠️ **ACHTUNG:** Dies löscht den User und alle zugehörigen Daten (Container, Tokens, etc.) **komplett**!
+
+**Authentifizierung:** (wie oben)
+
+**Parameter:**
+- `email` (required): Email-Adresse des zu löschenden Users
+
+**cURL Beispiel:**
+```bash
+curl -H "X-Debug-Token: your-secret-token" \
+  "http://localhost:5000/api/admin/debug?action=delete-email&email=test@example.com"
+```
+
+**Response (200 OK):**
+```json
+{
+  "action": "delete-email",
+  "message": "User test@example.com wurde gelöscht",
+  "user_id": 123
+}
+```
+
+**Response (404 Not Found):**
+```json
+{
+  "error": "User test@example.com nicht gefunden"
+}
+```
+
+**Response (500 Error):**
+```json
+{
+  "error": "Fehler beim Löschen: Docker container not found"
+}
+```
+
+---
+
+### 5️⃣ DELETE-TOKEN: Magic Link Tokens für User löschen
+
+**Endpoint:** `GET|POST /api/admin/debug?action=delete-token&email=test@example.com`
+
+Entfernt alle Magic Link Tokens für einen User (nützlich bei Token-Spam).
+
+**Authentifizierung:** (wie oben)
+
+**Parameter:**
+- `email` (required): Email-Adresse des Users
+
+**cURL Beispiel:**
+```bash
+curl -H "X-Debug-Token: your-secret-token" \
+  "http://localhost:5000/api/admin/debug?action=delete-token&email=test@example.com"
+```
+
+**Response (200 OK):**
+```json
+{
+  "action": "delete-token",
+  "message": "5 Tokens für test@example.com gelöscht",
+  "tokens_deleted": 5
+}
+```
+
+---
+
+### 6️⃣ INFO: Hilfe und verfügbare Actions
+
+**Endpoint:** `GET /api/admin/debug` oder `GET /api/admin/debug?action=info`
+
+Zeigt diese Hilfe mit allen verfügbaren Actions an.
+
+**Response (200 OK):**
+```json
+{
+  "endpoint": "/api/admin/debug",
+  "auth": "X-Debug-Token Header oder Admin JWT",
+  "actions": {
+    "view-logs": "Zeigt letzte 100 Zeilen der Logs",
+    "clear-logs": "Löscht alle Logs",
+    "list-users": "Listet alle registrierten User auf",
+    "delete-email": "Löscht User (Parameter: email=...)",
+    "delete-token": "Löscht Magic Link Tokens (Parameter: email=...)",
+    "info": "Diese Hilfe"
+  },
+  "examples": [...]
+}
+```
+
+---
+
+## 🔐 Authentifizierung
+
+Die DEBUG-API unterstützt zwei Authentifizierungsmethoden:
+
+### Methode 1: DEBUG_TOKEN (Empfohlen)
+
+```bash
+curl -H "X-Debug-Token: your-secret-token" \
+  "http://localhost:5000/api/admin/debug?action=list-users"
+```
+
+**Konfigurieren in `.env`:**
+```bash
+DEBUG_TOKEN=your-super-secret-token-here
+```
+
+**In Docker:**
+```bash
+docker exec spawner cat /app/.env | grep DEBUG_TOKEN
+```
+
+### Methode 2: JWT Admin Token
+
+```bash
+# 1. JWT Token von Admin abrufen
+curl -X POST http://localhost:5000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email": "admin@example.com"}'
+
+# Magic Link Token klicken/kopieren...
+
+# 2. Mit JWT Token DEBUG-API aufrufen
+curl -H "Authorization: Bearer $JWT_TOKEN" \
+  "http://localhost:5000/api/admin/debug?action=list-users"
+```
+
+---
+
+## 📋 Swagger API Spezifikation
+
+### Automatisch generiert:
+
+Flasgger generiert automatisch OpenAPI 3.0 Spezifikation aus den Python-Docstrings.
+
+**Verfügbar unter:**
+- **UI:** `http://localhost:5000/swagger`
+- **JSON:** `http://localhost:5000/openapi.json`
+- **YAML:** `http://localhost:5000/apispec.json`
+
+### Herunterladen & Importieren:
+
+```bash
+# OpenAPI JSON herunterladen
+curl http://localhost:5000/openapi.json > swagger.json
+
+# In Postman importieren:
+# 1. Postman öffnen
+# 2. File → Import
+# 3. swagger.json wählen
+```
+
+---
+
+## 🧪 Test-Beispiele
+
+### Test 1: Logs anzeigen
+```bash
+DEBUG_TOKEN=secret123
+curl -H "X-Debug-Token: $DEBUG_TOKEN" \
+  "http://localhost:5000/api/admin/debug?action=view-logs" | jq '.logs | head -20'
+```
+
+### Test 2: User auflisten
+```bash
+curl -H "X-Debug-Token: $DEBUG_TOKEN" \
+  "http://localhost:5000/api/admin/debug?action=list-users" | jq '.users[] | {email, state, is_blocked}'
+```
+
+### Test 3: User löschen (Vorsicht!)
+```bash
+curl -H "X-Debug-Token: $DEBUG_TOKEN" \
+  "http://localhost:5000/api/admin/debug?action=delete-email&email=test@example.com"
+```
+
+### Test 4: Tokens für User löschen
+```bash
+curl -H "X-Debug-Token: $DEBUG_TOKEN" \
+  "http://localhost:5000/api/admin/debug?action=delete-token&email=spam@example.com"
+```
+
+---
+
+## ⚠️ Wichtige Hinweise
+
+### DEBUG_TOKEN in Production
+
+**Sicherheit:**
+- ✅ Verwende starken, zufälligen Token (min. 32 Zeichen)
+- ✅ Speichere Token **nicht** im Git-Repo
+- ✅ Nur `.env` hat den Token (in `.gitignore`)
+- ⚠️ DEBUG-Endpoints sind nur für Admin/Development
+- ❌ Nicht in produktiven URLs exponieren
+
+**Best Practice:**
+```bash
+# Generiere sicheren Token
+python3 -c "import secrets; print(secrets.token_hex(32))"
+
+# In .env speichern (nicht committen!)
+DEBUG_TOKEN=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
+```
+
+### Datenschutz (DSGVO)
+
+Die DEBUG-API kann User komplett löschen (inkl. Containers, Tokens, Sessions).
+
+**Protokollierung:**
+```bash
+# Admin-Aktion wird geloggt
+[2026-02-02 17:30:45] User test@example.com vollständig gelöscht von Admin admin@example.com
+```
+
+**Verifikation:**
+```bash
+# Prüfe ob User gelöscht wurde
+docker exec spawner python3 -c "
+from app import app, db
+from models import User
+with app.app_context():
+    user = User.query.filter_by(email='test@example.com').first()
+    print('User found!' if user else 'User deleted ✓')
+"
+```
+
+---
+
+## 🔗 Integration in Tools
+
+### Postman
+```
+1. File → Import
+2. Link: http://localhost:5000/openapi.json
+3. Collection erstellt mit allen Endpoints
+```
+
+### Swagger Editor
+```
+1. https://editor.swagger.io öffnen
+2. File → Import URL
+3. http://localhost:5000/openapi.json eintragen
+```
+
+### Insomnia
+```
+1. Application → Preferences → Data
+2. "Import Data"
+3. URL: http://localhost:5000/openapi.json
+```
+
+---
+
+## 📊 OpenAPI Spezifikation
+
+**Version:** 3.0.0
+**Title:** Container Spawner API
+**Version:** 2.0.0
+**Base Path:** `/api/admin`
+
+### Security Schemes:
+- `jwt`: Bearer Token (JWT)
+- `debug_token`: X-Debug-Token Header
+
+### Endpoint Tags:
+- `Debug` - DEBUG-API Endpoints
+- `Admin` - Admin-Management Endpoints
+- `Auth` - Authentifizierung
+
+---
+
+## 🐛 Troubleshooting
+
+### Problem: Swagger UI zeigt 404
+
+```bash
+# Prüfe ob Flasgger installiert ist
+docker exec spawner pip list | grep flasgger
+
+# Falls nicht installiert:
+docker exec spawner pip install flasgger==0.9.7.1
+docker-compose restart spawner
+```
+
+### Problem: DEBUG_TOKEN wird nicht erkannt
+
+```bash
+# Prüfe ob DEBUG_TOKEN in .env definiert ist
+docker exec spawner cat /app/.env | grep DEBUG_TOKEN
+
+# Falls leer, füge hinzu:
+# DEBUG_TOKEN=your-secret-token
+docker-compose down
+docker-compose up -d
+```
+
+### Problem: OpenAPI JSON ist leer
+
+```bash
+# Prüfe Flasgger-Version
+docker exec spawner pip show flasgger
+
+# Falls veraltete Version:
+docker exec spawner pip install --upgrade flasgger
+docker-compose restart spawner
+```
+
+---
+
+## 📝 Dokumentation aktualisieren
+
+Bei neuen DEBUG-Endpoints:
+
+1. **Python-Docstring mit YAML aktualisieren**
+   ```python
+   @admin_bp.route('/debug/new-action', methods=['GET'])
+   def new_action():
+       """
+       Neue Aktion
+       ---
+       tags:
+         - Debug
+       parameters:
+         - name: param
+           in: query
+           type: string
+       responses:
+         200:
+           description: Erfolg
+       """
+   ```
+
+2. **Diese Dokumentation updaten** (guides/debug-api-swagger.md)
+
+3. **Flasgger generiert UI automatisch** unter `/swagger`
+
+---
+
+**Zuletzt aktualisiert:** 2026-02-02
+**Flasgger-Version:** 0.9.7.1
+**OpenAPI-Version:** 3.0.0

requirements.txt

@@ -3,6 +3,7 @@ flask-login==0.6.3
 flask-sqlalchemy==3.1.1
 flask-jwt-extended==4.6.0
 flask-cors==4.0.0
+flasgger==0.9.7.1
 werkzeug==3.0.1
 docker==6.1.0
 requests==2.28.0