(fix) Swagger/OpenAPI-Dokumentation implementieren

2025-06-30 23:38:48 +02:00
parent e2432510af
commit d40bfaac48
23 changed files with 1364 additions and 256 deletions
@@ -0,0 +1,160 @@
+# Swagger/OpenAPI Documentation
+
+## Übersicht
+
+Die Meldestelle API verfügt jetzt über eine vollständige Swagger/OpenAPI-Dokumentation, die eine interaktive Benutzeroberfläche zur Erkundung und Testung der API-Endpunkte bietet.
+
+## Zugriff auf die Dokumentation
+
+### Swagger UI
+- **URL**: `http://localhost:8080/swagger`
+- **Beschreibung**: Interaktive Benutzeroberfläche zur Erkundung der API
+- **Features**:
+  - Vollständige API-Dokumentation
+  - Interaktive Testmöglichkeiten
+  - Beispiel-Requests und -Responses
+  - Schema-Definitionen
+
+### OpenAPI Specification
+- **URL**: `http://localhost:8080/openapi`
+- **Beschreibung**: Raw OpenAPI 3.0.3 Spezifikation im YAML-Format
+- **Verwendung**: Kann für Code-Generierung oder Import in andere Tools verwendet werden
+
+## Dokumentierte Endpunkte
+
+### Basis-Endpunkte
+- `GET /health` - Gesundheitsprüfung des Services
+- `GET /api` - API-Informationen
+
+### Person Management (`/api/persons`)
+- `GET /api/persons` - Alle Personen abrufen
+- `POST /api/persons` - Neue Person erstellen
+- `GET /api/persons/{id}` - Person nach UUID abrufen
+- `PUT /api/persons/{id}` - Person aktualisieren
+- `DELETE /api/persons/{id}` - Person löschen
+- `GET /api/persons/oeps/{oepsSatzNr}` - Person nach OEPS-Nummer abrufen
+- `GET /api/persons/search?q={query}` - Personen suchen
+- `GET /api/persons/verein/{vereinId}` - Personen nach Verein-ID abrufen
+
+## Schema-Definitionen
+
+### Person
+```yaml
+Person:
+  type: object
+  properties:
+    id:
+      type: string
+      format: uuid
+    vorname:
+      type: string
+    nachname:
+      type: string
+    geburtsdatum:
+      type: string
+      format: date
+    oepsSatzNr:
+      type: string
+    vereinId:
+      type: string
+      format: uuid
+    email:
+      type: string
+      format: email
+    telefon:
+      type: string
+  required:
+    - vorname
+    - nachname
+```
+
+### Error
+```yaml
+Error:
+  type: object
+  properties:
+    error:
+      type: string
+  required:
+    - error
+```
+
+## Verwendung
+
+### 1. Server starten
+```bash
+./gradlew :server:run
+```
+
+### 2. Swagger UI öffnen
+Navigieren Sie zu `http://localhost:8080/swagger` in Ihrem Browser.
+
+### 3. API erkunden
+- Klicken Sie auf die verschiedenen Endpunkte, um Details zu sehen
+- Verwenden Sie "Try it out" um Requests direkt zu testen
+- Sehen Sie sich die Beispiel-Responses an
+
+### 4. OpenAPI Spec herunterladen
+Besuchen Sie `http://localhost:8080/openapi` um die vollständige OpenAPI-Spezifikation zu erhalten.
+
+## Erweiterung der Dokumentation
+
+### Neue Endpunkte hinzufügen
+Um neue API-Endpunkte zu dokumentieren, erweitern Sie die Datei:
+`server/src/main/resources/openapi.yaml`
+
+### Beispiel für neuen Endpunkt:
+```yaml
+/api/vereine:
+  get:
+    summary: Get all clubs
+    description: Retrieve a list of all clubs
+    tags:
+      - Clubs
+    responses:
+      '200':
+        description: List of clubs
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                $ref: '#/components/schemas/Verein'
+```
+
+## Technische Details
+
+### Dependencies
+- `io.ktor:ktor-server-openapi:3.1.2`
+- `io.ktor:ktor-server-swagger:3.1.2`
+
+### Konfiguration
+Die Swagger/OpenAPI-Konfiguration befindet sich in:
+- `server/src/main/kotlin/at/mocode/plugins/Routing.kt`
+- `server/src/main/resources/openapi.yaml`
+
+### Tests
+Automatisierte Tests für die Swagger-Funktionalität:
+- `server/src/test/kotlin/at/mocode/SwaggerTest.kt`
+
+## Nächste Schritte
+
+1. **Erweitern Sie die Dokumentation** für weitere API-Endpunkte (Vereine, Turniere, etc.)
+2. **Fügen Sie Authentifizierung hinzu** zur OpenAPI-Spezifikation wenn implementiert
+3. **Konfigurieren Sie Produktions-URLs** in der OpenAPI-Spezifikation
+4. **Implementieren Sie API-Versionierung** in der Dokumentation
+
+## Troubleshooting
+
+### Swagger UI lädt nicht
+- Überprüfen Sie, ob der Server läuft
+- Stellen Sie sicher, dass Port 8080 verfügbar ist
+- Prüfen Sie die Logs auf Fehler
+
+### OpenAPI Spec ist leer
+- Überprüfen Sie, ob `openapi.yaml` im Classpath verfügbar ist
+- Stellen Sie sicher, dass die Datei gültiges YAML enthält
+
+### API-Endpunkte fehlen in der Dokumentation
+- Erweitern Sie die `openapi.yaml` Datei
+- Starten Sie den Server neu nach Änderungen