2121190
/
IWS-OpenAPI
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
IWS-OpenAPI/Szenario/OpenAPI-Workshop-FoodExpres...

3.3 KiB
Raw Blame History

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
GET /restaurants/{id}/menu
GET /restaurants/{id}/orders		 POST /orders
GET /orders/{orderId}
PATCH /orders/{orderId}/status		 POST /customers
GET /customers/{id}
GET /customers/me
PATCH /customers/{id}
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