docs: add autogen-openapi feature request and plan
This commit is contained in:
parent
f9b24332cd
commit
8e8150331d
92
docs/FEATURE_PLAN-autogen-openapi.md
Normal file
92
docs/FEATURE_PLAN-autogen-openapi.md
Normal file
|
|
@ -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
|
||||||
|
|
||||||
|
````
|
||||||
55
docs/FEATURE_REQUEST-autogen-openapi.md
Normal file
55
docs/FEATURE_REQUEST-autogen-openapi.md
Normal file
|
|
@ -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
|
||||||
|
|
||||||
|
````
|
||||||
Loading…
Reference in New Issue
Block a user