{ "openapi": "3.0.3", "info": { "title": "Webshop System API", "description": "RESTful API für das Webshop-System mit vollständiger E-Commerce-Funktionalität", "version": "1.0.0", "contact": { "name": "Webshop System Support", "email": "support@webshop.local" }, "license": { "name": "GPL v3", "url": "https://www.gnu.org/licenses/gpl-3.0.html" } }, "servers": [ { "url": "https://api.webshop.local", "description": "Production Server" }, { "url": "https://api-dev.webshop.local", "description": "Development Server" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/products": { "get": { "summary": "Produktliste abrufen", "description": "Ruft eine paginierte Liste aller aktiven Produkte ab", "tags": ["Products"], "parameters": [ { "name": "page", "in": "query", "description": "Seitennummer", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "Anzahl Produkte pro Seite", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 50 } }, { "name": "category", "in": "query", "description": "Kategorie-ID für Filterung", "required": false, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Suchbegriff für Produktname/Beschreibung", "required": false, "schema": { "type": "string" } }, { "name": "min_price", "in": "query", "description": "Minimaler Preis", "required": false, "schema": { "type": "number" } }, { "name": "max_price", "in": "query", "description": "Maximaler Preis", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }, "400": { "description": "Ungültige Anfrage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nicht autorisiert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/products/{id}": { "get": { "summary": "Produktdetails abrufen", "description": "Ruft detaillierte Informationen zu einem spezifischen Produkt ab", "tags": ["Products"], "parameters": [ { "name": "id", "in": "path", "description": "Produkt-ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailResponse" } } } }, "404": { "description": "Produkt nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/categories": { "get": { "summary": "Kategorieliste abrufen", "description": "Ruft alle aktiven Kategorien ab", "tags": ["Categories"], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryListResponse" } } } } } } }, "/orders": { "post": { "summary": "Bestellung erstellen", "description": "Erstellt eine neue Bestellung", "tags": ["Orders"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } } }, "responses": { "201": { "description": "Bestellung erfolgreich erstellt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderResponse" } } } }, "400": { "description": "Ungültige Anfrage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/orders/{id}": { "get": { "summary": "Bestelldetails abrufen", "description": "Ruft detaillierte Informationen zu einer Bestellung ab", "tags": ["Orders"], "parameters": [ { "name": "id", "in": "path", "description": "Bestell-ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetailResponse" } } } }, "404": { "description": "Bestellung nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "summary": "Bestellung aktualisieren", "description": "Aktualisiert den Status einer Bestellung", "tags": ["Orders"], "parameters": [ { "name": "id", "in": "path", "description": "Bestell-ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderRequest" } } } }, "responses": { "200": { "description": "Bestellung erfolgreich aktualisiert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Ungültige Anfrage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Bestellung nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/customers/register": { "post": { "summary": "Kunde registrieren", "description": "Registriert einen neuen Kunden", "tags": ["Customers"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRegisterRequest" } } } }, "responses": { "201": { "description": "Kunde erfolgreich registriert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRegisterResponse" } } } }, "400": { "description": "Ungültige Anfrage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "E-Mail bereits registriert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/customers/login": { "post": { "summary": "Kunde anmelden", "description": "Meldet einen Kunden an und gibt JWT-Token zurück", "tags": ["Customers"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoginRequest" } } } }, "responses": { "200": { "description": "Anmeldung erfolgreich", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoginResponse" } } } }, "401": { "description": "Ungültige Anmeldedaten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/customers/{id}/profile": { "get": { "summary": "Kundenprofil abrufen", "description": "Ruft das Profil eines Kunden ab", "tags": ["Customers"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Kunden-ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerProfileResponse" } } } }, "401": { "description": "Nicht autorisiert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Kunde nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "summary": "Kundenprofil aktualisieren", "description": "Aktualisiert das Profil eines Kunden", "tags": ["Customers"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Kunden-ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerRequest" } } } }, "responses": { "200": { "description": "Profil erfolgreich aktualisiert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Ungültige Anfrage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nicht autorisiert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/products/{id}/reviews": { "get": { "summary": "Produktbewertungen abrufen", "description": "Ruft alle Bewertungen für ein Produkt ab", "tags": ["Reviews"], "parameters": [ { "name": "id", "in": "path", "description": "Produkt-ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Seitennummer", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Anzahl Bewertungen pro Seite", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "sort", "in": "query", "description": "Sortierung", "required": false, "schema": { "type": "string", "enum": ["newest", "oldest", "rating"], "default": "newest" } }, { "name": "rating", "in": "query", "description": "Filter nach Bewertung", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5 } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewListResponse" } } } }, "404": { "description": "Produkt nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "Bewertung erstellen", "description": "Erstellt eine neue Bewertung für ein Produkt", "tags": ["Reviews"], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Produkt-ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReviewRequest" } } } }, "responses": { "201": { "description": "Bewertung erfolgreich erstellt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReviewResponse" } } } }, "400": { "description": "Ungültige Anfrage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Nicht autorisiert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Bewertung bereits erstellt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/newsletter/subscribe": { "post": { "summary": "Newsletter abonnieren", "description": "Abonniert den Newsletter", "tags": ["Newsletter"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterSubscribeRequest" } } } }, "responses": { "201": { "description": "Newsletter erfolgreich abonniert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterSubscribeResponse" } } } }, "400": { "description": "Ungültige Anfrage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "E-Mail bereits abonniert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/newsletter/unsubscribe": { "post": { "summary": "Newsletter abbestellen", "description": "Bestellt den Newsletter ab", "tags": ["Newsletter"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterUnsubscribeRequest" } } } }, "responses": { "200": { "description": "Newsletter erfolgreich abbestellt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Ungültige Anfrage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "E-Mail nicht abonniert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/stats": { "get": { "summary": "API-Statistiken abrufen", "description": "Ruft allgemeine Statistiken der API ab", "tags": ["Statistics"], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsResponse" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Product": { "type": "object", "properties": { "id": { "type": "integer", "description": "Produkt-ID" }, "name": { "type": "string", "description": "Produktname" }, "description": { "type": "string", "description": "Produktbeschreibung" }, "price": { "type": "number", "format": "float", "description": "Preis" }, "category_id": { "type": "integer", "description": "Kategorie-ID" }, "category_name": { "type": "string", "description": "Kategoriename" }, "stock": { "type": "integer", "description": "Lagerbestand" }, "active": { "type": "boolean", "description": "Aktiv-Status" }, "created_at": { "type": "string", "format": "date-time", "description": "Erstellungsdatum" } } }, "ProductListResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "ProductDetailResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "allOf": [ { "$ref": "#/components/schemas/Product" }, { "type": "object", "properties": { "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } } } } ] } } }, "Category": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "parent_id": { "type": "integer", "nullable": true }, "sort_order": { "type": "integer" }, "active": { "type": "boolean" } } }, "CategoryListResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } }, "CreateOrderRequest": { "type": "object", "required": ["customer_name", "customer_email", "items"], "properties": { "customer_name": { "type": "string", "description": "Kundenname" }, "customer_email": { "type": "string", "format": "email", "description": "Kunden-E-Mail" }, "customer_phone": { "type": "string", "description": "Kundentelefon" }, "items": { "type": "array", "items": { "type": "object", "required": ["product_id", "product_name", "quantity", "price"], "properties": { "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "price": { "type": "number", "format": "float" } } } } } }, "CreateOrderResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "order_id": { "type": "integer" }, "total_amount": { "type": "number", "format": "float" } } }, "message": { "type": "string" } } }, "Order": { "type": "object", "properties": { "id": { "type": "integer" }, "customer_name": { "type": "string" }, "customer_email": { "type": "string" }, "total_amount": { "type": "number", "format": "float" }, "status": { "type": "string", "enum": ["pending", "confirmed", "shipped", "delivered", "cancelled"] }, "created_at": { "type": "string", "format": "date-time" } } }, "OrderDetailResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "allOf": [ { "$ref": "#/components/schemas/Order" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": "number", "format": "float" }, "total_price": { "type": "number", "format": "float" } } } } } } ] } } }, "UpdateOrderRequest": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "enum": ["pending", "confirmed", "shipped", "delivered", "cancelled"] } } }, "CustomerRegisterRequest": { "type": "object", "required": ["email", "password", "first_name", "last_name"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" }, "newsletter": { "type": "boolean" } } }, "CustomerRegisterResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "customer_id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "token": { "type": "string" } } }, "message": { "type": "string" } } }, "CustomerLoginRequest": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } }, "CustomerLoginResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "customer_id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "token": { "type": "string" } } }, "message": { "type": "string" } } }, "CustomerProfileResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" }, "newsletter": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "last_login": { "type": "string", "format": "date-time" }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "phone": { "type": "string" }, "is_default": { "type": "boolean" } } } } } } } }, "UpdateCustomerRequest": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" }, "newsletter": { "type": "boolean" } } }, "Review": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "customer_id": { "type": "integer" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": "string" }, "comment": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "helpful_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "ReviewListResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "summary": { "type": "object", "properties": { "average_rating": { "type": "number", "format": "float" }, "total_reviews": { "type": "integer" }, "rating_distribution": { "type": "array", "items": { "type": "object", "properties": { "rating": { "type": "integer" }, "count": { "type": "integer" } } } } } } } } } }, "CreateReviewRequest": { "type": "object", "required": ["rating", "title", "comment"], "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": "string", "minLength": 3, "maxLength": 100 }, "comment": { "type": "string", "minLength": 10, "maxLength": 1000 } } }, "CreateReviewResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "review_id": { "type": "integer" } } }, "message": { "type": "string" } } }, "NewsletterSubscribeRequest": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "preferences": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "integer" } }, "frequency": { "type": "string", "enum": ["weekly", "monthly"] } } } } }, "NewsletterSubscribeResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "subscriber_id": { "type": "integer" } } }, "message": { "type": "string" } } }, "NewsletterUnsubscribeRequest": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" } } }, "StatsResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "products": { "type": "integer" }, "categories": { "type": "integer" }, "orders": { "type": "integer" }, "customers": { "type": "integer" } } } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } }, "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" }, "status_code": { "type": "integer" } } } } }, "tags": [ { "name": "Products", "description": "Produkt-bezogene Endpoints" }, { "name": "Categories", "description": "Kategorie-bezogene Endpoints" }, { "name": "Orders", "description": "Bestellungs-bezogene Endpoints" }, { "name": "Customers", "description": "Kunden-bezogene Endpoints" }, { "name": "Reviews", "description": "Bewertungs-bezogene Endpoints" }, { "name": "Newsletter", "description": "Newsletter-bezogene Endpoints" }, { "name": "Statistics", "description": "Statistik-bezogene Endpoints" } ] }