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
This commit is contained in:
XPS\Micro
parent
be859ab77b
commit
2c8cf47564
73
admin_api.py
73
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: <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')
|
||||
|
|
|
|||
25
app.py
25
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)
|
||||
|
|
|
|||
192
docs/guides/debug-api-cheatsheet.md
Normal file
192
docs/guides/debug-api-cheatsheet.md
Normal file
|
|
@ -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
|
||||
457
docs/guides/debug-api-swagger.md
Normal file
457
docs/guides/debug-api-swagger.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user