# OpenAPI Workshop

**FoodExpress - API Dokumentation erstellen**

*Workshop-Material*

---

## Das Szenario: FoodExpress

> **Willkommen bei FoodExpress!**
>
> Ihr wurdet als Entwicklerteam beauftragt, die API-Dokumentation für FoodExpress zu erstellen - eine innovative Plattform zur Online-Essensbestellung. Die Plattform verbindet hungrige Kunden mit lokalen Restaurants und ermöglicht eine nahtlose Bestellabwicklung.

### Die Geschäftsanforderungen

FoodExpress möchte seinen Partnern und Entwicklern eine standardisierte, gut dokumentierte API zur Verfügung stellen. Eure Aufgabe ist es, eine vollständige OpenAPI-Spezifikation zu erstellen, die alle notwendigen Endpunkte beschreibt.

### Die Kernfunktionen der Plattform

|  | **Restaurants** | **Bestellungen** | **Kunden** |
|--|-----------------|------------------|------------|
| **Beschreibung** | Verwaltung und Anzeige von Restaurants und deren Speisekarten | Erstellen, Abrufen und Verwalten von Bestellungen | Kundenverwaltung und Profilinformationen |
| **Endpunkte** | `GET /restaurants`<br>`GET /restaurants/{id}/menu` <br>`GET /restaurants/{id}/orders`  | `POST /orders`<br>`GET /orders/{orderId}`<br>`PATCH /orders/{orderId}/status` | `POST /customers`<br>`GET /customers/{id}`<br>`GET /customers/me`<br>`PATCH /customers/{id}`<br>`DELETE /customers/{id}` |

> **Eure Mission**
>
> Im Laufe dieses Workshops werdet ihr schrittweise eine vollständige OpenAPI 3.0 Spezifikation für FoodExpress erstellen. Dabei lernt ihr alle wichtigen Konzepte und Best Practices kennen, die ihr für professionelle API-Dokumentation benötigt.

---

## API Endpunkte - Vollständige Übersicht

Diese Endpunkte sollt ihr im Verlauf des Workshops in eurer OpenAPI-Spezifikation definieren:

### Restaurant-Endpunkte

#### `GET` /restaurants

Liste aller verfügbaren Restaurants abrufen

- **Query-Parameter:** Pagination (limit, offset) für große Ergebnismengen
- **Header-Parameter:** AcceptLanguage

---

#### `GET` /restaurants/{id}/menu

Speisekarte eines bestimmten Restaurants abrufen

- **Path-Parameter:** Restaurant-ID als Pflichtparameter
- **Header-Parameter:** AcceptLanguage

---

#### `GET` /restaurants/{id}/orders

Liste an Bestellungen pro Restaurant

- **Path-Parameter:** Restaurant-ID als Pflichtparameter
- **Header-Parameter:** AcceptLanguage


### Bestell-Endpunkte

#### `POST` /orders

Neue Bestellung aufgeben

- **Request Body:** Bestelldetails inkl. Kunde, Restaurant, Artikel
- **Header-Parameter:** IdempotencyKey

---

#### `GET` /orders/{orderId}

Details einer spezifischen Bestellung abrufen

- **Path-Parameter:** Bestellnummer als Pflichtparameter

---

#### `PATCH` /orders/{orderId}/status

Bestellstatus aktualisieren (z.B. 'in Zubereitung', 'unterwegs')

- **Request Body:** Neuer Status-Wert

### Kunden-Endpunkte

#### `POST` /customers

Neuen Kunden registrieren

- **Request Body:** Kundendaten (Name, E-Mail, Adresse, etc.)
- **Header-Parameter:** IdempotencyKey

---

#### `GET` /customers/{id}

Kundenprofil abrufen

- **Path-Parameter:** Kunden-ID als Pflichtparameter

---

#### `GET` /customers/me

Eigenes Kundenprofil des authentifizierten Benutzers abrufen

---

#### `PATCH` /customers/{id}

Kundendaten aktualisieren

- **Request Body:** Zu aktualisierende Felder

---

#### `DELETE` /customers/{id}

Kundenkonto löschen

- **Hinweis:** Irreversible Aktion - Bestätigung erforderlich