openapi: 3.0.3
info:
  title: Burger API
  description: API for managing burger orders and related operations
  version: 1.0.0
servers:
  - url: <BURGER_API_HOST>/api
    description: Burger API server
paths:
  /:
    get:
      tags:
        - utility
      summary: Get server status
      description: Returns basic server status and order statistics.
      operationId: getStatus
      responses:
        '200':
          description: Server status and order statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: up
                  activeOrders:
                    type: integer
                    example: 2
                  totalOrders:
                    type: integer
                    example: 10
                  registeredUsers:
                    type: integer
                    description: Number of registered users in the system
                    example: 5
                  timestamp:
                    type: string
                    format: date-time
                    example: '2025-05-06T12:00:00Z'
                required:
                  - status
                  - activeOrders
                  - totalOrders
                  - registeredUsers
                  - timestamp
  /openapi:
    get:
      tags:
        - utility
      summary: Get OpenAPI specification
      description: |
        Returns the OpenAPI specification, by default in YAML format.

        To request JSON format, use the query parameter `?format=json` or set the `Accept: application/json` header.
      operationId: getOpenApiSpec
      responses:
        '200':
          description: OpenAPI specification in YAML or JSON format
          content:
            text/yaml:
              schema:
                type: string
                example: |
                  openapi: 3.0.3
                  info:
                    title: Burger API
                    version: 1.0.0
                  ...
  /orders:
    get:
      tags:
        - orders
      summary: Get all orders
      description: Returns a list of all orders in the system
      operationId: getOrders
      parameters:
        - name: userId
          in: query
          description: Filter orders by userId
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: Filter orders by status (comma-separated for multiple, e.g. pending,ready)
          required: false
          schema:
            type: string
        - name: last
          in: query
          description: Filter orders created in the last X minutes/hours (e.g. 60m, 2h)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderResponse'
    post:
      tags:
        - orders
      summary: Create a new order
      description: |
        Places a new order with burgers (requires userId).
        French fries are included as a side for every burger order.

        Limitations:
        - Maximum 5 active orders per user
        - Maximum 50 burgers total per order
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: User is not registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many active orders for this user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orders/{orderId}:
    get:
      tags:
        - orders
      summary: Get order by ID
      description: Retrieves an order by its ID
      operationId: getOrderById
      parameters:
        - name: orderId
          in: path
          description: ID of the order
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Order details found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - orders
      summary: Cancel an order
      description: |
        Cancels an order if it has not yet been started (status must be 'pending').

        The `userId` query parameter is required (e.g., `?userId=user123`).
        If `userId` is missing or does not match the `userId` of the order, the request will be rejected.
      operationId: cancelOrder
      parameters:
        - name: orderId
          in: path
          description: ID of the order
          required: true
          schema:
            type: string
        - name: userId
          in: query
          description: ID of the user requesting the cancellation (required)
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Order cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '403':
          description: User is not authorized to cancel this order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order not found or cannot be cancelled (not in pending status)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Order ID or user ID is missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /burgers:
    get:
      tags:
        - burgers
      summary: Get all burgers
      description: Returns a list of all burgers
      operationId: getBurgers
      responses:
        '200':
          description: List of burgers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MenuItem'
  /burgers/{id}:
    get:
      tags:
        - burgers
      summary: Get burger by ID
      description: Retrieves a specific burger by its ID
      operationId: getBurgerById
      parameters:
        - name: id
          in: path
          description: ID of the burger
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Burger details found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MenuItem'
        '404':
          description: Burger not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /toppings:
    get:
      tags:
        - toppings
      summary: Get all toppings
      description: Returns a list of all toppings
      operationId: getToppings
      parameters:
        - name: category
          in: query
          description: Filter toppings by category
          required: false
          schema:
            type: string
      responses:
        '200':
          description: List of toppings
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MenuItem'
  /toppings/categories:
    get:
      tags:
        - toppings
      summary: Get all topping categories
      description: Returns a list of all topping categories
      operationId: getToppingCategories
      responses:
        '200':
          description: List of topping categories
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /toppings/{id}:
    get:
      tags:
        - toppings
      summary: Get topping by ID
      description: Retrieves a specific topping by its ID
      operationId: getToppingById
      parameters:
        - name: id
          in: path
          description: ID of the topping
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Topping details found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MenuItem'
        '404':
          description: Topping not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /images/{filepath}:
    get:
      tags:
        - images
      summary: Get an image
      description: Retrieves an image from Azure Blob Storage
      operationId: getImage
      parameters:
        - name: filepath
          in: path
          description: Path to the image file in Azure Blob Storage
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Image found and returned
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/gif:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
            image/svg+xml:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid request - image path is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Image not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    MenuCategory:
      type: string
      enum:
        - burger
        - drink
        - side
        - topping
    MenuItem:
      type: object
      properties:
        id:
          type: string
          example: 'burger-1'
        category:
          $ref: '#/components/schemas/MenuCategory'
        name:
          type: string
          example: 'Margherita Burger'
        description:
          type: string
          example: 'Classic burger with tomato sauce and mozzarella'
        price:
          type: number
          format: float
          example: 12.99
      required:
        - id
        - category
        - name
        - description
        - price
    OrderStatus:
      type: string
      enum:
        - pending
        - in-preparation
        - ready
        - completed
        - cancelled
      description: >
        - pending: Order has been created but not yet started
        - in-preparation: Order is being prepared
        - ready: Order is ready for pickup
        - completed: Order has been picked up
        - cancelled: Order has been cancelled
    OrderItem:
      type: object
      properties:
        burgerId:
          type: string
          example: 'burger-1'
        quantity:
          type: integer
          minimum: 1
          example: 1
          description: Must be a positive integer (greater than 0). Orders with zero or negative quantity will be rejected with a 400 error.
        extraToppingIds:
          type: array
          items:
            type: string
          description: Optional list of extra topping IDs to add to the burger
          example: ['topping-1', 'topping-2']
      required:
        - burgerId
        - quantity
    Order:
      type: object
      properties:
        id:
          type: string
          example: '1618057820123'
        userId:
          type: string
          example: 'user123'
        createdAt:
          type: string
          format: date-time
          description: ISO date string of when the order was created
          example: '2025-04-10T14:30:00Z'
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        estimatedCompletionAt:
          type: string
          format: date-time
          description: ISO date string for estimated completion time
          example: '2025-04-10T15:00:00Z'
        completedAt:
          type: string
          format: date-time
          description: ISO date string for when the order was completed (undefined until completed)
          example: '2025-04-10T15:10:00Z'
        readyAt:
          type: string
          format: date-time
          description: ISO date string for when the order was ready (undefined until ready)
          example: '2025-04-10T15:05:00Z'
        nickname:
          type: string
          description: Optional nickname for the order
          example: 'John'
        totalPrice:
          type: number
          format: float
          example: 22.98
        status:
          $ref: '#/components/schemas/OrderStatus'
      required:
        - id
        - userId
        - createdAt
        - items
        - estimatedCompletionAt
        - totalPrice
        - status
    OrderResponse:
      type: object
      description: Order object returned by the API (userId is omitted for privacy)
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        estimatedCompletionAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
          description: ISO date string for when the order was completed (undefined until completed)
        nickname:
          type: string
          description: Optional nickname for the order
        totalPrice:
          type: number
          format: float
        status:
          $ref: '#/components/schemas/OrderStatus'
      required:
        - id
        - createdAt
        - items
        - estimatedCompletionAt
        - totalPrice
        - status
    CreateOrderRequest:
      type: object
      properties:
        userId:
          type: string
          example: 'user123'
        nickname:
          type: string
          description: Optional nickname for the order (only first 10 chars displayed)
          example: 'John'
        items:
          type: array
          description: List of burger items (maximum 50 burgers total across all items)
          items:
            type: object
            properties:
              burgerId:
                type: string
                example: 'burger-1'
              quantity:
                type: integer
                minimum: 1
                example: 1
              extraToppingIds:
                type: array
                items:
                  type: string
                description: Optional list of extra topping IDs to add to the burger
                example: ['topping-1', 'topping-2']
            required:
              - burgerId
              - quantity
      required:
        - userId
        - items
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: 'Order must contain at least one item'
      required:
        - error