From 2c8cf475647b98b465b8b3c8167c1f965910b137 Mon Sep 17 00:00:00 2001 From: "XPS\\Micro" Date: Mon, 2 Feb 2026 17:25:24 +0100 Subject: [PATCH] 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 | 73 ++++- app.py | 25 ++ docs/guides/debug-api-cheatsheet.md | 192 ++++++++++++ docs/guides/debug-api-swagger.md | 457 ++++++++++++++++++++++++++++ requirements.txt | 1 + 5 files changed, 736 insertions(+), 12 deletions(-) create mode 100644 docs/guides/debug-api-cheatsheet.md create mode 100644 docs/guides/debug-api-swagger.md diff --git a/admin_api.py b/admin_api.py index 72b3e47..66e1497 100644 --- a/admin_api.py +++ b/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: - 1. DEBUG_TOKEN Header: X-Debug-Token: - 2. Oder Admin JWT Token - - Actions: - - view-logs: Zeigt letzte 100 Zeilen der Logs - - clear-logs: Löscht alle Logs - - delete-email: Entfernt User und alle zugehörigen Daten - Parameter: ?email=test@example.com - - delete-token: Entfernt Magic Link Tokens für Email - Parameter: ?email=test@example.com + --- + tags: + - Debug + parameters: + - name: action + in: query + type: string + required: true + enum: + - view-logs + - clear-logs + - 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') diff --git a/app.py b/app.py index 8896349..dab9f0a 100644 --- a/app.py +++ b/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) diff --git a/docs/guides/debug-api-cheatsheet.md b/docs/guides/debug-api-cheatsheet.md new file mode 100644 index 0000000..830c813 --- /dev/null +++ b/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 diff --git a/docs/guides/debug-api-swagger.md b/docs/guides/debug-api-swagger.md new file mode 100644 index 0000000..5bf6019 --- /dev/null +++ b/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 diff --git a/requirements.txt b/requirements.txt index 0fd1c90..5d29d44 100644 --- a/requirements.txt +++ b/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