openapi: 3.0.0
security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

tags:
  - name: Orders
    description: API endpoints for managing orders

paths:
  /api/orders:
    post:
      summary: Create an order from cart (adds current cart items to order)
      description: |
        Creates an order from the user's current cart items. 
        All ACTIVE cart items will be added to the order and their status will be changed from ACTIVE to PENDING.
        The cart will be marked as CONVERTED after the order is created.
      tags: [Orders]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                deliveryAddress:
                  type: string
                  example: "123 Main Street, City, State, ZIP"
                  description: The delivery address for the order
                  required: true
                promoCode:
                  type: string
                  example: "SAVE10"
                  description: Optional promo code to apply discount
              required:
                - deliveryAddress
      responses:
        201:
          description: Order created successfully. Cart items status changed from ACTIVE to PENDING.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Order created successfully"
                  data:
                    type: object
                    properties:
                      order:
                        type: object
        400:
          description: Bad request (e.g., cart is empty, invalid promo code)
        401:
          description: Unauthorized
        404:
          description: Cart not found
        500:
          description: Internal server error

    get:
      summary: Get all orders (Admin only)
      tags: [Orders]
      security:
        - BearerAuth: []
      parameters:
        - name: status
          in: query
          description: Filter orders by status
          schema:
            type: string
            enum: [PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
        - name: userId
          in: query
          description: Filter orders by user ID
          schema:
            type: string
      responses:
        200:
          description: A list of orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Orders fetched successfully"
                  data:
                    type: object
                    properties:
                      orders:
                        type: array
                        items:
                          type: object
        401:
          description: Unauthorized
        403:
          description: Forbidden (Admin only)
        500:
          description: Internal server error

  /api/orders/my-orders:
    get:
      summary: Get user's orders
      tags: [Orders]
      security:
        - BearerAuth: []
      responses:
        200:
          description: A list of user's orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Orders fetched successfully"
                  data:
                    type: object
                    properties:
                      orders:
                        type: array
                        items:
                          type: object
        401:
          description: Unauthorized
        500:
          description: Internal server error

  /api/orders/{id}:
    get:
      summary: Get an order by ID
      tags: [Orders]
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the order
          schema:
            type: string
            example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        200:
          description: Order details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Order fetched successfully"
                  data:
                    type: object
                    properties:
                      order:
                        type: object
        401:
          description: Unauthorized
        404:
          description: Order not found
        500:
          description: Internal server error

  /api/orders/{id}/status:
    put:
      summary: Update order status (Admin only)
      tags: [Orders]
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the order
          schema:
            type: string
            example: "123e4567-e89b-12d3-a456-426614174000"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
                  example: "CONFIRMED"
                  description: The new status of the order
                  required: true
      responses:
        200:
          description: Order status updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Order status updated successfully"
                  data:
                    type: object
                    properties:
                      order:
                        type: object
        400:
          description: Bad request (invalid status)
        401:
          description: Unauthorized
        403:
          description: Forbidden (Admin only)
        404:
          description: Order not found
        500:
          description: Internal server error

  /api/orders/{id}/cancel:
    put:
      summary: Cancel an order
      tags: [Orders]
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the order
          schema:
            type: string
            example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        200:
          description: Order cancelled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Order cancelled successfully"
                  data:
                    type: object
                    properties:
                      order:
                        type: object
        400:
          description: Bad request (order cannot be cancelled)
        401:
          description: Unauthorized
        404:
          description: Order not found
        500:
          description: Internal server error

