spawner/docs/guides/debug-api-swagger.md

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:

# 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):

{
  "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):

{
  "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):

{
  "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):

{
  "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:

curl -H "X-Debug-Token: your-secret-token" \
  "http://localhost:5000/api/admin/debug?action=delete-email&email=test@example.com"

Response (200 OK):

{
  "action": "delete-email",
  "message": "User test@example.com wurde gelöscht",
  "user_id": 123
}

Response (404 Not Found):

{
  "error": "User test@example.com nicht gefunden"
}

Response (500 Error):

{
  "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:

curl -H "X-Debug-Token: your-secret-token" \
  "http://localhost:5000/api/admin/debug?action=delete-token&email=test@example.com"

Response (200 OK):

{
  "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):

{
  "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)

curl -H "X-Debug-Token: your-secret-token" \
  "http://localhost:5000/api/admin/debug?action=list-users"

Konfigurieren in .env:

DEBUG_TOKEN=your-super-secret-token-here

In Docker:

docker exec spawner cat /app/.env | grep DEBUG_TOKEN

Methode 2: JWT Admin Token

# 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:

# 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

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

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!)

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

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:

# 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:

# Admin-Aktion wird geloggt
[2026-02-02 17:30:45] User test@example.com vollständig gelöscht von Admin admin@example.com

Verifikation:

# 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

# 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

# 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

# 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

   @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