161 lines
4.1 KiB
Markdown
161 lines
4.1 KiB
Markdown
# 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
|