diff --git a/docs/FEATURE_PLAN-autogen-openapi.md b/docs/FEATURE_PLAN-autogen-openapi.md new file mode 100644 index 0000000..9ec7132 --- /dev/null +++ b/docs/FEATURE_PLAN-autogen-openapi.md @@ -0,0 +1,92 @@ +````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 + +```` \ No newline at end of file diff --git a/docs/FEATURE_REQUEST-autogen-openapi.md b/docs/FEATURE_REQUEST-autogen-openapi.md new file mode 100644 index 0000000..1624bd8 --- /dev/null +++ b/docs/FEATURE_REQUEST-autogen-openapi.md @@ -0,0 +1,55 @@ +````markdown + +# Feature Request: Autogenerierte OpenAPI / Swagger Spec + +**Kurzbeschreibung**: Automatische Erzeugung einer OpenAPI (Swagger) Spec aus dem Express‑Backend (dev‑only), so dass neue Routen sofort und ohne manuelles Nacharbeiten in der API‑Dokumentation erscheinen. + +**Motivation / Nutzen**: +- Single source of truth: Routen im Code sind die einzige Quelle; keine manuelle openapi.json Pflege. +- Entwicklerfreundlich: Neue Route → Doku beim nĂ€chsten Serverstart sichtbar. +- Schnelle Übersicht fĂŒr QA und API‑Reviewer via Swagger UI. +- Reduziert Drift zwischen Implementierung und Dokumentation. + +--- + +## Aktueller Stand +- Backend ist Express‑basiert, Routen sind statisch in `backend/src/routes` definiert. +- `express-fileupload` wird als Middleware verwendet. +- Keine automatische OpenAPI Spec derzeit vorhanden. + +--- + +## Anforderungen an das Feature +1. Beim lokalen Dev‑Start soll eine OpenAPI Spec erzeugt werden (z. B. mit `swagger-autogen` oder `express-oas-generator`). +2. Eine Swagger UI (nur in Dev) soll unter `/api/docs` erreichbar sein und die erzeugte Spec anzeigen. +3. Automatisch erkannte Endpunkte mĂŒssen sichtbar sein; fĂŒr komplexe FĂ€lle (multipart Uploads) sollen einfache Hints / Overrides möglich sein. +4. Keine Breaking Changes am Produktions‑Startverhalten: Autogen nur in `NODE_ENV !== 'production'` oder per opt‑in env var. +5. Erzeugte Spec soll ins Repo (z. B. `docs/openapi.json`) optional geschrieben werden können (fĂŒr CI/Review). + +--- + +## Minimaler Scope (MVP) +- Dev‑only Integration: Generator installiert und beim Start einmal ausgefĂŒhrt. +- Swagger UI unter `/api/docs` mit generierter Spec. +- Kurze Anleitung im `README.dev.md` wie man die Doku lokal öffnet. + +--- + +## Akzeptanzkriterien +- [ ] Swagger UI zeigt alle standardmĂ€ĂŸig erkannten Endpoints an. +- [ ] Upload‑Endpoints erscheinen (Pfad erkannt). Falls requestBody fehlt, ist ein klarer Hinweis dokumentiert. +- [ ] Feature ist deaktivierbar in `production`. +- [ ] Optionaler Export: `docs/openapi.json` kann per npm script erzeugt werden. + +--- + +## GeschĂ€tzter Aufwand (MVP) +- Setup & smoke test: 1–2h +- Anpassungen fĂŒr Upload‑Hints + kleine Nacharbeiten: 1–2h +- Optionales Export/CI: +1h + +--- + +**Erstellt am**: 16. November 2025 + +```` \ No newline at end of file