````markdown
# Feature Plan: Autogenerierte OpenAPI / Swagger Spec

**Branch:** `feature/autogen-openapi`  
**Datum:** 16. November 2025

## 🎯 Ziel
Einfaches Developer‑Experience Feature, das beim lokalen Start des Backends automatisch eine OpenAPI Spec erzeugt und eine Swagger UI zur Verfügung stellt. Entwickler müssen beim Anlegen neuer Routen die Doku nicht mehr manuell nachpflegen.

---

## 🔍 Scope
- Dev‑only: Generierung beim lokalen Start oder per npm script.
- Swagger UI unter `/api/docs` (Dev) mit der generierten Spec.
- Optionaler Export der Spec nach `docs/openapi.json` für CI/Review.
- Keine invasive Änderung an Produktionsstart.

---

## 📐 Architektur‑Überblick
### Warum das funktioniert für dieses Projekt
- Routen werden statisch importiert und in `backend/src/routes/index.js` mit klaren Basispfaden registriert.
- Viele Routen nutzen konstante Pfadangaben (`backend/src/constants.js`) oder feste Strings.
- Daher erkennen Generatoren die meisten Endpunkte zuverlässig.

### Grenzen
- Multipart Uploads (express-fileupload) werden in der Regel als Pfad erkannt, die requestBody Beschreibung (multipart schema) kann fehlen und erfordert kleine Hints.
- Komplexe Response‑Schemas (detaillierte components/schemas) sind nicht automatisch vollständig präzise; diese können später ergänzt werden.

---

## 🔧 Implementierungs‑Schritte
### Phase 0 — Vorbereitung (30–60 min)
- Branch anlegen: `feature/autogen-openapi` (bereits erfolgt)
- Dev‑Dokumentation anpassen: `README.dev.md` Hinweis wie Doku geöffnet wird

### Phase 1 — MVP Integration (1–2h)
1. Installiere dev‑Dependency: `swagger-autogen` oder `express-oas-generator` (oder `swagger-jsdoc + swagger-ui-express` falls JSDoc bevorzugt wird).  
2. Füge ein npm script hinzu: `npm run generate:openapi` (erzeugt `docs/openapi.json`).  
3. Bei Dev‑Start: Generator einmal ausführen und Spec in memory oder als file verfügbar machen.  
4. Mount Swagger UI unter `/api/docs` nur in Dev.

**Ergebnis:** Swagger UI listet automatisch erkannte Endpunkte.

### Phase 2 — Nacharbeit & Hints (1–2h)
- Prüfe Upload‑Endpoints (z. B. `/upload`, `/upload/batch`) und füge ggf. kleine Hints oder manuelle Ergänzungen zur requestBody‑Definition hinzu (in `docs/openapi.json` oder per generator config).
- Optional: ergänze components/schemas für die wichtigsten Responses (Groups, Image, UploadResult).

### Phase 3 — CI / Export (0.5–1h)
- Optionales npm script für CI, das `npm run generate:openapi` ausführt und das Ergebnis im Artefact bereitstellt.  
- Optional: OpenAPI Validator in CI laufen lassen (z. B. `swagger-cli validate`) um Spec‑Fehler früh zu erkennen.

---

## ⏱️ Zeitplan & Aufwand
- MVP (Dev UI + generate once): 1–2 Stunden
- Upload Hints + kleine Spec‑Fixes: 1–2 Stunden
- Optional: CI/Export + Validator: 0.5–1 Stunde

**Total (realistisch, MVP+fixes): 2–4 Stunden**

---

## ✅ Acceptance Criteria
- [ ] Feature Branch mit Integration existiert (`feature/autogen-openapi`).
- [ ] `npm run dev` zeigt Swagger UI unter `/api/docs` mit generierter Spec.
- [ ] Alle standardmäßigen Routen sind in der Spec enthalten (Smoke Test).
- [ ] Upload‑Endpoints erkannt; falls requestBody fehlt, dokumentierter Hinweis in PR.
- [ ] Feature ist deaktiviert in `production`.
- [ ] Optional: `docs/openapi.json` kann per script erzeugt werden.

---

## ⚠️ Risiken & Mitigations
- Risiko: Generator erkennt Upload requestBody nicht korrekt.  
  Mitigation: Manuelle Hint‑Block oder kleine post‑processing Schritte in `generate:openapi` Script.

- Risiko: Spec generiert sensitive Pfade/fields (management tokens).  
  Mitigation: Filter/Transformation im Export‑Script oder nur generiertes file in CI/Review; Swagger UI dev‑only.

---

## ✅ Next Steps (konkret)
1. Push Branch `feature/autogen-openapi` remote (falls noch nicht geschehen).  
2. Ich implementiere MVP: installiere Generator, führe einmaligen Lauf aus, mounte Swagger UI und liefere `docs/openapi.json` und eine Liste der Endpunkte, die Hints brauchen.  
3. PR mit Implementation + Docs.  
4. Review und Nachbesserung des Specs (Uploads/Schemas).


**Erstellt am:** 16. November 2025

````