API updadte
This commit is contained in:
249
README.md
249
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:**
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user