matthias.lotz
6332b82c6a
- replace bearer auth with session+CSRF flow and add admin user directory - update frontend moderation flow, force password change gate, and new CLI - refresh changelog/docs/feature plan + ensure swagger dev experience
2.2 KiB
2.2 KiB
# 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