460 lines
11 KiB
YAML
460 lines
11 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Food Express API
|
|
description: >
|
|
API for managing the FoodExpress restaurants, orders, and customers.
|
|
version: 1.0.0
|
|
|
|
servers:
|
|
- url: http://localhost:4004/api/v1
|
|
description: Local development servers
|
|
- url: https://{stage}.foodexpress.com/api/v1
|
|
description: Stage server
|
|
variables:
|
|
stage:
|
|
description: Stage
|
|
enum:
|
|
- dev
|
|
- test
|
|
default: dev
|
|
- url: https://foodexpress.com/api/v1
|
|
description: Production server
|
|
|
|
tags:
|
|
- name: Restaurants
|
|
- name: Orders
|
|
- name: Customers
|
|
|
|
paths:
|
|
/restaurants:
|
|
get:
|
|
tags: [Restaurants]
|
|
summary: List restaurants
|
|
description: Retrieve a paginated list of restaurants.
|
|
security: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/Limit"
|
|
- $ref: "#/components/parameters/Offset"
|
|
- $ref: "#/components/parameters/AcceptLanguage"
|
|
responses:
|
|
"200":
|
|
description: A paginated list of restaurants
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Restaurant"
|
|
pagination:
|
|
$ref: "#/components/schemas/Pagination"
|
|
|
|
/restaurants/{id}/menu:
|
|
get:
|
|
tags: [Restaurants]
|
|
summary: Get restaurant menu
|
|
security: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/RestaurantId"
|
|
- $ref: "#/components/parameters/AcceptLanguage"
|
|
responses:
|
|
"200":
|
|
description: "Menu for the restaurant"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Menu"
|
|
"404":
|
|
description: Restaurant not found
|
|
|
|
/restaurants/{id}/orders:
|
|
get:
|
|
tags: [Orders, Restaurants]
|
|
summary: List orders for a restaurant
|
|
description: Retrieve a paginated list of orders for a specific restaurant.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RestaurantId"
|
|
- $ref: "#/components/parameters/Limit"
|
|
- $ref: "#/components/parameters/Offset"
|
|
responses:
|
|
"200":
|
|
description: A paginated list of orders
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Order"
|
|
pagination:
|
|
$ref: "#/components/schemas/Pagination"
|
|
|
|
/orders:
|
|
post:
|
|
tags: [Orders]
|
|
summary: Create a new order
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CreateOrderRequest"
|
|
parameters:
|
|
- $ref: "#/components/parameters/IdempotencyKey"
|
|
responses:
|
|
"201":
|
|
description: Order created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Order"
|
|
"400":
|
|
description: Invalid request
|
|
|
|
/orders/{orderId}:
|
|
get:
|
|
tags: [Orders]
|
|
summary: Get order by ID
|
|
parameters:
|
|
- $ref: "#/components/parameters/OrderId"
|
|
responses:
|
|
"200":
|
|
description: Order details
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Order"
|
|
"404":
|
|
description: Order not found
|
|
|
|
/orders/{orderId}/status:
|
|
patch:
|
|
tags: [Orders]
|
|
summary: Update order status
|
|
description: Update the status of an existing order.
|
|
parameters:
|
|
- $ref: "#/components/parameters/OrderId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UpdateOrderStatusRequest"
|
|
responses:
|
|
"200":
|
|
description: Order status updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Order"
|
|
"409":
|
|
description: Invalid status transition
|
|
|
|
/customers:
|
|
post:
|
|
tags: [Customers]
|
|
summary: Create a customer
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CreateCustomerRequest"
|
|
examples:
|
|
Customer:
|
|
$ref: "#/components/examples/CustomerRequest"
|
|
parameters:
|
|
- $ref: "#/components/parameters/IdempotencyKey"
|
|
responses:
|
|
"201":
|
|
description: Customer created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Customer"
|
|
/customers/me:
|
|
get:
|
|
tags: [Customers]
|
|
summary: Get current customer
|
|
description: Returns the authenticated customer's profile
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/CustomerDetails"
|
|
|
|
/customers/{id}:
|
|
get:
|
|
tags: [Customers]
|
|
summary: Get customer by ID
|
|
parameters:
|
|
- $ref: "#/components/parameters/CustomerId"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/CustomerDetails"
|
|
"404":
|
|
description: Customer not found
|
|
|
|
patch:
|
|
tags: [Customers]
|
|
summary: Update customer details
|
|
parameters:
|
|
- $ref: "#/components/parameters/CustomerId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UpdateCustomerRequest"
|
|
examples:
|
|
Customer:
|
|
$ref: "#/components/examples/CustomerRequest"
|
|
responses:
|
|
"200":
|
|
description: Customer updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Customer"
|
|
|
|
delete:
|
|
tags: [Customers]
|
|
summary: Delete customer
|
|
parameters:
|
|
- $ref: "#/components/parameters/CustomerId"
|
|
responses:
|
|
"204":
|
|
description: Customer deleted
|
|
|
|
components:
|
|
parameters:
|
|
RestaurantId:
|
|
name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: "09ede9cb-0031-4469-9144-dec6b564f1c0"
|
|
|
|
OrderId:
|
|
name: orderId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: "e17aca0c-c956-4a0d-afec-b117a9926e2c"
|
|
|
|
CustomerId:
|
|
name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: "18e1d8a2-e7ca-458f-a997-2cc80754105f"
|
|
|
|
Limit:
|
|
name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 100
|
|
default: 20
|
|
examples: [20]
|
|
|
|
Offset:
|
|
name: offset
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
default: 0
|
|
examples: [0]
|
|
|
|
IdempotencyKey:
|
|
in: header
|
|
name: Idempotency-Key
|
|
required: false
|
|
description: Unique key to prevent duplicate orders
|
|
schema:
|
|
type: string
|
|
|
|
AcceptLanguage:
|
|
in: header
|
|
name: Accept-Language
|
|
required: false
|
|
description: Preferred language for localized strings.
|
|
schema:
|
|
type: string
|
|
example: "de-DE"
|
|
|
|
schemas:
|
|
Restaurant:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
examples: ["465db18f-6fc0-48e1-804a-156d0df29392"]
|
|
name:
|
|
type: string
|
|
examples: ["Thai Food"]
|
|
address:
|
|
type: string
|
|
examples: ["Hauptstraße 9, 68259 Mannheim"]
|
|
|
|
Menu:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/MenuItem"
|
|
|
|
MenuItem:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
examples: ["9f062baf-236b-44fe-8d30-88cecb02c26b"]
|
|
name:
|
|
type: string
|
|
examples: ["Cheeseburger"]
|
|
price:
|
|
type: number
|
|
examples: [3.99]
|
|
|
|
Order:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
examples: ["28c0bc0d-9d17-4b74-9885-84a4cd7c761e"]
|
|
restaurantId:
|
|
type: string
|
|
examples: ["73591883-8aa4-4a2d-a411-abf42220a824"]
|
|
customerId:
|
|
type: string
|
|
examples: ["706f645d-a420-4984-a913-c9a6e0c677f2"]
|
|
status:
|
|
$ref: "#/components/schemas/OrderStatus"
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/OrderItem"
|
|
totalAmount:
|
|
type: number
|
|
examples: [29.95]
|
|
|
|
OrderItem:
|
|
type: object
|
|
properties:
|
|
menuItemId:
|
|
type: string
|
|
examples: ["359d9b4a-c8a2-4457-a04a-fecddadad64f"]
|
|
quantity:
|
|
type: integer
|
|
minimum: 1
|
|
examples: [1]
|
|
|
|
OrderStatus:
|
|
type: string
|
|
enum:
|
|
- CREATED
|
|
- CONFIRMED
|
|
- PREPARING
|
|
- READY
|
|
- DELIVERED
|
|
- CANCELLED
|
|
examples: ["CREATED"]
|
|
|
|
CreateOrderRequest:
|
|
type: object
|
|
required: [restaurantId, customerId, items]
|
|
properties:
|
|
restaurantId:
|
|
type: string
|
|
examples: ["435cb941-3483-4e80-acc1-6454f1f948b5"]
|
|
customerId:
|
|
type: string
|
|
examples: ["433569a1-d4d8-4073-ab1a-d26339c747c3"]
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/OrderItem"
|
|
|
|
UpdateOrderStatusRequest:
|
|
type: object
|
|
required: [status]
|
|
properties:
|
|
status:
|
|
$ref: "#/components/schemas/OrderStatus"
|
|
|
|
Customer:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
examples: ["1a7830a6-8e0f-43b2-a0e0-4479cb0acf7d"]
|
|
name:
|
|
type: string
|
|
examples: ["Max Mustermann"]
|
|
email:
|
|
type: string
|
|
examples: ["max.mustermann@gmail.com"]
|
|
|
|
CreateCustomerRequest:
|
|
type: object
|
|
required: [name, email]
|
|
properties:
|
|
name:
|
|
type: string
|
|
email:
|
|
type: string
|
|
|
|
UpdateCustomerRequest:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
email:
|
|
type: string
|
|
|
|
Pagination:
|
|
type: object
|
|
properties:
|
|
limit:
|
|
type: integer
|
|
examples: [20]
|
|
offset:
|
|
type: integer
|
|
examples: [0]
|
|
total:
|
|
type: integer
|
|
examples: [35]
|
|
|
|
responses:
|
|
CustomerDetails:
|
|
description: "Customer details"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Customer"
|
|
|
|
examples:
|
|
CustomerRequest:
|
|
value:
|
|
name: "Max Mustermann"
|
|
email: "max.mustermann@gmail.com"
|
|
|
|
securitySchemes:
|
|
BasicAuth:
|
|
type: http
|
|
scheme: basic
|
|
|
|
ApiKeyAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: X-API-Key
|
|
|
|
security:
|
|
- BasicAuth: []
|