openapi: 3.1.0
info:
  title: Pizza API
  description: API for managing pizza orders and related operations
  version: 1.0.0
servers:
  - url: <PIZZA_API_HOST>/api
    description: Pizza 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: Pizza 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 pizzas (requires userId).
        
        Order limits:
        - Maximum 50 pizzas per order
        - Maximum 5 active orders per user
        
        The estimated completion time is as follows:
        - 3-5 minutes for 1-2 pizzas, plus 1 minute for each additional pizza.
        
        Order statuses are updated automatically:
        - Orders move from 'pending' to 'in-preparation' 1-3 minutes after creation.
        - Orders move from 'in-preparation' to 'completed' 2-3 minutes around their estimated completion time.
      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 (e.g., missing required fields, invalid pizza/topping IDs, invalid quantities, or order exceeds 50 pizzas limit)
          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'
  /pizzas:
    get:
      tags:
        - pizzas
      summary: Get all pizzas
      description: Returns a list of all pizzas
      operationId: getPizzas
      responses:
        '200':
          description: List of pizzas
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MenuItem'
  /pizzas/{id}:
    get:
      tags:
        - pizzas
      summary: Get pizza by ID
      description: Retrieves a specific pizza by its ID
      operationId: getPizzaById
      parameters:
        - name: id
          in: path
          description: ID of the pizza
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Pizza details found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MenuItem'
        '404':
          description: Pizza 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:
        - pizza
        - drink
        - side
        - topping
    MenuItem:
      type: object
      properties:
        id:
          type: string
          example: "pizza-1"
        category:
          $ref: '#/components/schemas/MenuCategory'
        name:
          type: string
          example: "Margherita Pizza"
        description:
          type: string
          example: "Classic pizza 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:
        pizzaId:
          type: string
          example: "pizza-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 pizza
          example: ["topping-1", "topping-2"]
      required:
        - pizzaId
        - quantity
    Order:
      type: object
      properties:
        id:
          type: string
          example: "1618057820123"
        userId:
          type: string
          example: "user123"
        nickname:
          type: string
          description: Optional nickname for the order
          example: "My Pizza Order"
        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"
        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)
        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 that will be displayed instead of order ID (first 8 characters will be shown)
          example: "My Pizza Order"
        items:
          type: array
          items:
            type: object
            properties:
              pizzaId:
                type: string
                example: "pizza-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 pizza
                example: ["topping-1", "topping-2"]
            required:
              - pizzaId
              - quantity
      required:
        - userId
        - items
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: "Order must contain at least one item"
      required:
        - error