From 0fb028d19a9302a9a2dd29f61f257ca21c106ff8 Mon Sep 17 00:00:00 2001 From: Martin Date: Sat, 8 Nov 2025 22:19:33 +0100 Subject: [PATCH] API updadte --- README.md | 249 +++++++++++++++++++++++++----- config/packages/api_platform.yaml | 6 + 2 files changed, 216 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 7d22618..5b098ee 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,10 @@ Eine moderne Webanwendung zur Immobilienberechnung, entwickelt mit Symfony 7.3, ## Features -- **REST-API**: Vollständige REST-API mit automatischer Dokumentation über API Platform +- **REST-API**: Vollständige REST-API mit API Platform 4.2 +- **Swagger/OpenAPI**: Automatische interaktive API-Dokumentation (Swagger UI) - **Web-Interface**: Benutzerfreundliche Weboberfläche mit Twig-Templates +- **Immobilien-Management**: Vollständige CRUD-Operationen für Immobilien mit automatischen Berechnungen - **User Management**: Benutzerverwaltung mit Rollenbasierter Zugriffskontrolle (USER, ADMIN, MODERATOR) - **Docker-Setup**: Vollständig containerisierte Entwicklungsumgebung - **Datenbank-Migrationen**: Versionskontrollierte Datenbankschema-Verwaltung mit Doctrine @@ -56,13 +58,21 @@ Dieser Befehl: docker-compose exec web composer install ``` -### 4. Datenbank-Schema erstellen +### 4. Bundle-Assets installieren + +```bash +docker-compose exec web php bin/console assets:install public --symlink --relative +``` + +Dieser Schritt ist wichtig für die Swagger UI (CSS, JS, Bilder). + +### 5. Datenbank-Schema erstellen ```bash docker-compose exec web php bin/console doctrine:migrations:migrate --no-interaction ``` -### 5. Cache leeren +### 6. Cache leeren ```bash docker-compose exec web php bin/console cache:clear @@ -73,41 +83,21 @@ docker-compose exec web php bin/console cache:clear ### Anwendung aufrufen - **Web-Interface**: http://localhost:8080 -- **API-Dokumentation**: http://localhost:8080/api +- **API-Dokumentation (Swagger UI)**: http://localhost:8080/api/docs.html +- **API Entrypoint (Hydra)**: http://localhost:8080/api +- **OpenAPI Spezifikation (JSON)**: http://localhost:8080/api/docs?format=json - **phpMyAdmin**: http://localhost:8081 - Server: `db` - Benutzer: `root` - Passwort: `root` -### REST-API Endpoints +### Schnellstart API -#### User-API +Die vollständige API-Dokumentation mit allen Endpunkten, Beispielen und interaktiven Tests finden Sie im Abschnitt **[API-Dokumentation](#api-dokumentation)** weiter unten. -| Methode | Endpoint | Beschreibung | -|---------|----------|--------------| -| GET | `/api/users` | Alle User abrufen | -| GET | `/api/users/{id}` | Einzelnen User abrufen | -| POST | `/api/users` | Neuen User erstellen | -| PUT | `/api/users/{id}` | User aktualisieren | -| DELETE | `/api/users/{id}` | User löschen | - -#### Beispiel: User erstellen - -```bash -curl -X POST http://localhost:8080/api/users \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Max Mustermann", - "email": "max@example.com", - "role": "user" - }' -``` - -#### Beispiel: Alle User abrufen - -```bash -curl http://localhost:8080/api/users -``` +Wichtigste Endpunkte: +- **Immobilien**: `/api/immobilies` (GET, POST, PATCH, DELETE) +- **Benutzer**: `/api/users` (GET, POST, PUT, DELETE) ## Datenbank-Schema @@ -116,11 +106,38 @@ curl http://localhost:8080/api/users | Feld | Typ | Beschreibung | |------|-----|--------------| | id | INT | Primärschlüssel (Auto-Increment) | -| name | VARCHAR(255) | Benutzername | +| name | VARCHAR(255) | Benutzername (min. 2 Zeichen) | | email | VARCHAR(255) | E-Mail-Adresse (Unique) | | role | ENUM | Benutzerrolle (user, admin, moderator) | | created_at | DATETIME | Erstellungsdatum | +### Immobilien-Tabelle + +| Feld | Typ | Beschreibung | +|------|-----|--------------| +| id | INT | Primärschlüssel (Auto-Increment) | +| verwalter_id | INT | Foreign Key zu User (Verwalter der Immobilie) | +| adresse | VARCHAR(255) | Vollständige Adresse (5-255 Zeichen) | +| preis | DECIMAL | Kaufpreis oder Miete | +| flaeche | DECIMAL | Wohnfläche in m² | +| garage | BOOLEAN | Hat Garage? (Standard: false) | +| zimmer | INT | Anzahl Zimmer (> 0) | +| baujahr | INT | Baujahr (1800-2100, optional) | +| typ | ENUM | Immobilientyp (wohnung, haus, grundstueck, gewerbe, buero) | +| beschreibung | TEXT | Freitextbeschreibung (optional) | +| verfuegbar | BOOLEAN | Verfügbarkeit (Standard: true) | +| balkon_flaeche | INT | Balkonfläche in m² (optional) | +| keller_flaeche | INT | Kellerfläche in m² (optional) | +| etage | INT | Stockwerk (optional) | +| heizungstyp | VARCHAR(255) | Art der Heizung (optional) | +| nebenkosten | DECIMAL | Monatliche Nebenkosten (optional) | +| created_at | DATETIME | Erstellungsdatum | +| updated_at | DATETIME | Letzte Aktualisierung | + +**Berechnete Felder (nicht in DB gespeichert):** +- `preis_pro_qm`: Preis / Fläche +- `gesamtflaeche`: Fläche + Balkon + Keller + ## Entwicklung ### Neue Entity erstellen @@ -279,6 +296,20 @@ Apache-VirtualHost-Konfiguration befindet sich in `docker/apache/000-default.con ## Fehlerbehebung +### Swagger UI lädt ohne CSS/JS (Assets fehlen) + +Wenn die Swagger UI unter http://localhost:8080/api/docs.html zwar lädt, aber keine Styles/Formatierung hat: + +```bash +# Bundle-Assets installieren +docker-compose exec web php bin/console assets:install public --symlink --relative + +# Cache leeren +docker-compose exec web php bin/console cache:clear +``` + +Danach sollten alle CSS-, JS- und Bilddateien unter `/bundles/apiplatform/` verfügbar sein. + ### Container starten nicht ```bash @@ -332,20 +363,160 @@ services: ## API-Dokumentation -Die vollständige API-Dokumentation ist verfügbar unter: -- **Swagger UI**: http://localhost:8080/api +Die Anwendung nutzt **API Platform** zur automatischen Generierung von OpenAPI/Swagger-Dokumentation. Die interaktive Dokumentation ermöglicht es, alle API-Endpunkte direkt im Browser zu testen. -Die API unterstützt mehrere Formate: -- JSON-LD (Standard) -- JSON -- HTML +### Swagger UI (Interaktive Dokumentation) -Beispiel für JSON-Format: +Die **Swagger UI** bietet eine vollständige, interaktive Dokumentation aller API-Endpunkte: + +**URL**: http://localhost:8080/api/docs.html + +Features: +- Übersicht aller verfügbaren Endpunkte +- Interaktives Testen direkt im Browser +- Detaillierte Request/Response-Schemas +- Automatische Validierung von Parametern +- Try-it-out Funktion für alle Operationen + +### OpenAPI Spezifikation + +Die OpenAPI-Spezifikation (ehemals Swagger) kann in verschiedenen Formaten abgerufen werden: + +#### OpenAPI JSON-Format +```bash +curl "http://localhost:8080/api/docs?format=json" +``` + +#### JSON-LD Format (Hydra) +```bash +curl http://localhost:8080/api/docs.jsonld +``` + +#### HTML Format (Swagger UI) +```bash +curl http://localhost:8080/api/docs.html +# oder im Browser öffnen: http://localhost:8080/api/docs.html +``` + +### API-Formate + +Die API unterstützt mehrere Content-Type-Formate: + +| Format | Content-Type | Beschreibung | +|--------|--------------|--------------| +| **JSON-LD** | `application/ld+json` | Standard-Format mit Linked Data Kontext (Hydra) | +| **JSON** | `application/json` | Einfaches JSON-Format | +| **HTML** | `text/html` | HTML-Darstellung (Swagger UI) | + +#### Beispiel: JSON-Format verwenden ```bash curl -H "Accept: application/json" http://localhost:8080/api/users ``` +#### Beispiel: JSON-LD Format (Standard) + +```bash +curl http://localhost:8080/api/users +# oder explizit: +curl -H "Accept: application/ld+json" http://localhost:8080/api/users +``` + +### Verfügbare Ressourcen + +#### Immobilien-Endpunkte + +| Methode | Endpoint | Beschreibung | +|---------|----------|--------------| +| GET | `/api/immobilies` | Alle Immobilien abrufen (mit Pagination) | +| GET | `/api/immobilies/{id}` | Einzelne Immobilie abrufen | +| POST | `/api/immobilies` | Neue Immobilie erstellen | +| PATCH | `/api/immobilies/{id}` | Immobilie teilweise aktualisieren | +| DELETE | `/api/immobilies/{id}` | Immobilie löschen | + +#### User-Endpunkte + +| Methode | Endpoint | Beschreibung | +|---------|----------|--------------| +| GET | `/api/users` | Alle User abrufen (mit Pagination) | +| GET | `/api/users/{id}` | Einzelnen User abrufen | +| POST | `/api/users` | Neuen User erstellen | +| PUT | `/api/users/{id}` | User vollständig ersetzen | +| DELETE | `/api/users/{id}` | User löschen | + +### Beispiele + +#### Immobilie erstellen + +```bash +curl -X POST http://localhost:8080/api/immobilies \ + -H "Content-Type: application/json" \ + -d '{ + "verwalter": "/api/users/1", + "adresse": "Hauptstraße 123, 12345 Musterstadt", + "preis": "250000", + "flaeche": "85.5", + "zimmer": 3, + "typ": "wohnung", + "garage": true, + "balkonFlaeche": 8, + "baujahr": 2020 + }' +``` + +#### User erstellen + +```bash +curl -X POST http://localhost:8080/api/users \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Max Mustermann", + "email": "max@example.com", + "role": "user" + }' +``` + +#### Immobilien mit Filter abrufen (Pagination) + +```bash +# Erste Seite (Standard) +curl http://localhost:8080/api/immobilies + +# Zweite Seite +curl http://localhost:8080/api/immobilies?page=2 +``` + +#### Einzelne Immobilie aktualisieren (PATCH) + +```bash +curl -X PATCH http://localhost:8080/api/immobilies/1 \ + -H "Content-Type: application/merge-patch+json" \ + -d '{ + "preis": "260000", + "verfuegbar": false + }' +``` + +### Berechnete Felder + +Die Immobilien-Entity bietet automatisch berechnete Felder: + +- **preisProQm**: Berechnet automatisch den Preis pro Quadratmeter +- **gesamtflaeche**: Summiert Wohnfläche + Balkonfläche + Kellerfläche + +Diese Felder sind schreibgeschützt (read-only) und werden automatisch bei jeder Abfrage berechnet. + +### Hydra-Unterstützung + +Bei Verwendung des JSON-LD Formats (Standard) bietet die API Hydra-Unterstützung: + +- **@context**: Beschreibt die Linked Data Struktur +- **@id**: IRI (Internationalized Resource Identifier) der Ressource +- **@type**: Typ der Ressource +- **hydra:member**: Array der Ressourcen in Collections +- **hydra:totalItems**: Gesamtanzahl der Elemente +- **hydra:view**: Pagination-Links (first, last, next, previous) + ## Sicherheitshinweise **Wichtig für Produktion:** diff --git a/config/packages/api_platform.yaml b/config/packages/api_platform.yaml index 5659ba5..2913a99 100644 --- a/config/packages/api_platform.yaml +++ b/config/packages/api_platform.yaml @@ -33,3 +33,9 @@ api_platform: jsonld: ['application/ld+json'] jsonopenapi: ['application/vnd.openapi+json'] html: ['text/html'] + swagger: + versions: [3] + api_keys: + apiKey: + name: Authorization + type: header