greggy/immorechner
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

API updadte

Browse Source
This commit is contained in:
Martin
2025-11-08 22:19:33 +01:00
parent 58c7907915
commit 0fb028d19a
2 changed files with 216 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

249
README.md
View File

@@ -4,8 +4,10 @@ Eine moderne Webanwendung zur Immobilienberechnung, entwickelt mit Symfony 7.3,
## Features ## 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 - **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) - **User Management**: Benutzerverwaltung mit Rollenbasierter Zugriffskontrolle (USER, ADMIN, MODERATOR)
- **Docker-Setup**: Vollständig containerisierte Entwicklungsumgebung - **Docker-Setup**: Vollständig containerisierte Entwicklungsumgebung
- **Datenbank-Migrationen**: Versionskontrollierte Datenbankschema-Verwaltung mit Doctrine - **Datenbank-Migrationen**: Versionskontrollierte Datenbankschema-Verwaltung mit Doctrine
@@ -56,13 +58,21 @@ Dieser Befehl:
docker-compose exec web composer install 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 ```bash
docker-compose exec web php bin/console doctrine:migrations:migrate --no-interaction docker-compose exec web php bin/console doctrine:migrations:migrate --no-interaction
``` ```
### 5. Cache leeren ### 6. Cache leeren
```bash ```bash
docker-compose exec web php bin/console cache:clear docker-compose exec web php bin/console cache:clear
@@ -73,41 +83,21 @@ docker-compose exec web php bin/console cache:clear
### Anwendung aufrufen ### Anwendung aufrufen
- **Web-Interface**: http://localhost:8080 - **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 - **phpMyAdmin**: http://localhost:8081
- Server: `db` - Server: `db`
- Benutzer: `root` - Benutzer: `root`
- Passwort: `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 | Wichtigste Endpunkte:
|---------|----------|--------------| - **Immobilien**: `/api/immobilies` (GET, POST, PATCH, DELETE)
| GET | `/api/users` | Alle User abrufen | - **Benutzer**: `/api/users` (GET, POST, PUT, DELETE)
| 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
```
## Datenbank-Schema ## Datenbank-Schema
@@ -116,11 +106,38 @@ curl http://localhost:8080/api/users
| Feld | Typ | Beschreibung | | Feld | Typ | Beschreibung |
|------|-----|--------------| |------|-----|--------------|
| id | INT | Primärschlüssel (Auto-Increment) | | 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) | | email | VARCHAR(255) | E-Mail-Adresse (Unique) |
| role | ENUM | Benutzerrolle (user, admin, moderator) | | role | ENUM | Benutzerrolle (user, admin, moderator) |
| created_at | DATETIME | Erstellungsdatum | | 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 ## Entwicklung
### Neue Entity erstellen ### Neue Entity erstellen
@@ -279,6 +296,20 @@ Apache-VirtualHost-Konfiguration befindet sich in `docker/apache/000-default.con
## Fehlerbehebung ## 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 ### Container starten nicht
```bash ```bash
@@ -332,20 +363,160 @@ services:
## API-Dokumentation ## API-Dokumentation
Die vollständige API-Dokumentation ist verfügbar unter: 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.
- **Swagger UI**: http://localhost:8080/api
Die API unterstützt mehrere Formate: ### Swagger UI (Interaktive Dokumentation)
- JSON-LD (Standard)
- JSON
- HTML
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 ```bash
curl -H "Accept: application/json" http://localhost:8080/api/users 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 ## Sicherheitshinweise
**Wichtig für Produktion:** **Wichtig für Produktion:**

6
config/packages/api_platform.yaml
View File

@@ -33,3 +33,9 @@ api_platform:
jsonld: ['application/ld+json'] jsonld: ['application/ld+json']
jsonopenapi: ['application/vnd.openapi+json'] jsonopenapi: ['application/vnd.openapi+json']
html: ['text/html'] html: ['text/html']
swagger:
versions: [3]
api_keys:
apiKey:
name: Authorization
type: header