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
55 lines
2.2 KiB
Markdown
55 lines
2.2 KiB
Markdown
````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
|
||
|
||
```` |