Add API versioning policy and sync docs OpenAPI spec

docs/api-versioning.md

@@ -0,0 +1,57 @@
+# API Versionierung und Deprecation Policy
+
+## Ziel
+
+Diese Policy definiert eine reproduzierbare Versionierungsstrategie fuer `helpyourneighbour`, damit API-Clients stabil bleiben und Breaking Changes planbar sind.
+
+## Versionierungsmodell
+
+- Basispfad-Versionierung: `/v1/...`, `/v2/...`
+- Aktueller Stand dieses Repos ist funktional `v1`.
+- Fuer die laufende Migration gilt: bestehende Routen ohne Prefix bleiben bis zur vollstaendigen Umstellung als Legacy-Compat aktiv.
+
+## Semantik
+
+- **Minor Change (non-breaking):** neue optionale Felder, neue Endpunkte, neue optionale Query-Parameter.
+- **Major Change (breaking):** Umbenennung/Entfernung von Feldern, strictere Validierung mit API-Break, geaenderte Fehlersemantik.
+- Non-breaking Aenderungen bleiben innerhalb derselben Major API (`v1`).
+- Breaking Aenderungen erzeugen eine neue Major API (`v2`).
+
+## Deprecation-Regeln
+
+Bei geplanter Entfernung eines Endpunkts/Felds:
+
+1. Markierung als `deprecated: true` in OpenAPI.
+2. Deprecation-Hinweis in Response-Headern:
+   - `Deprecation: true`
+   - `Sunset: <RFC-1123 Datum>`
+   - optional `Link: <migrations-url>; rel=\"deprecation\"`
+3. Changelog-Eintrag und Migrationshinweise im Repo (`docs/`).
+4. Mindestfrist bis Removal: **90 Tage**.
+
+## Kompatibilitaetsgarantien
+
+- JSON-Felder werden nicht ohne neue Major API entfernt.
+- Typen werden nicht stillschweigend geaendert.
+- Neue Pflichtfelder werden nicht in bestehende Request-Bodies von `v1` eingefuehrt.
+
+## Fehlerverhalten
+
+- Fehlerobjekte folgen stabil dem Muster `{ "error": ... }`.
+- Neue Fehlercodes werden additive eingefuehrt.
+- Bereits genutzte HTTP-Statuscodes bleiben stabil, ausser bei neuer Major API.
+
+## Rollout-Prozess fuer Breaking Changes
+
+1. ADR erstellen (Design + Impact).
+2. `v2` Endpunkt parallel einfuehren.
+3. `v1` als deprecated markieren (Header + OpenAPI).
+4. 90-Tage-Frist einhalten.
+5. Nach Frist `v1` entfernen.
+
+## Definition of Done fuer API-Aenderungen
+
+- OpenAPI aktualisiert (`/openapi.yaml` und `docs/openapi.yaml`).
+- Changelog/Migrationshinweis vorhanden.
+- Contract-Tests fuer geaenderte Endpunkte aktualisiert.
+- Breaking vs non-breaking explizit im PR beschrieben.