openapi: 3.1.0
info:
  title: E-commerce API
  version: 1.0.0
  description: |
    This is an e-commerce API spec for a storefront. 
    It includes authentication, product browsing, cart, and checkout operations.
    Auth is token-based. Explore, test, and mock this API freely.

servers:
  - url: https://api.demo-ecommerce.com/v1
    description: Production environment
  - url: https://api.dev.demo-ecommerce.com/v1
    description: Development environment

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

  schemas:
    Product:
      type: object
      required: [id, name, price, stock, category]
      properties:
        id:
          type: string
          format: uuid
          example: eda5cbc1-a615-4da5-ae73-4a33a9acfb6a
        name:
          type: string
          example: Worry Management
        description:
          type: string
          example: Mr street sell would civil. People through shake southern force.
        price:
          type: number
          format: float
          example: 91.37
        category:
          type: string
          example: wrong
        image_url:
          type: string
          format: uri
          example: https://dummyimage.com/766x809
        stock:
          type: integer
          example: 94
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CartItem:
      type: object
      required: [product_id, quantity]
      properties:
        product_id:
          type: string
          format: uuid
        quantity:
          type: integer
          minimum: 1

    Address:
      type: object
      required: [line1, city, state, postal_code, country]
      properties:
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        state:
          type: string
        postal_code:
          type: string
        country:
          type: string

    Order:
      type: object
      required: [id, items, total_amount, status, created_at]
      properties:
        id:
          type: string
          format: uuid
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartItem'
        total_amount:
          type: number
        status:
          type: string
          enum: [pending, confirmed, shipped, delivered]
        created_at:
          type: string
          format: date-time

paths:
  /auth/register:
    post:
      summary: Create a new user account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
                name:
                  type: string
      responses:
        '201':
          description: User created
        '400':
          description: Invalid input

  /auth/login:
    post:
      summary: Login and get access token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Authenticated successfully
        '401':
          description: Unauthorized

  /products:
    get:
      summary: List all products with filters
      parameters:
        - name: category
          in: query
          schema:
            type: string
        - name: search
          in: query
          schema:
            type: string
        - name: min_price
          in: query
          schema:
            type: number
        - name: max_price
          in: query
          schema:
            type: number
      responses:
        '200':
          description: List of products
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'

  /products/{id}:
    get:
      summary: Get product details by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

  /cart:
    get:
      summary: Get current user's cart
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Your cart items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CartItem'

  /cart/items:
    post:
      summary: Add item to cart
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartItem'
      responses:
        '200':
          description: Item added to cart

  /checkout:
    post:
      summary: Checkout and place order
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address_id, payment_method_id]
              properties:
                address_id:
                  type: string
                payment_method_id:
                  type: string
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

  /orders:
    get:
      summary: List your past orders
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Order history
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'

  /orders/{orderId}:
    get:
      summary: Get order details
      security:
        - BearerAuth: []
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Order detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

  /addresses:
    get:
      summary: Get your saved addresses
      security:
        - BearerAuth: []
      responses:
        '200':
          description: List of saved addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Address'

    post:
      summary: Add a new address
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Address'
      responses:
        '201':
          description: Address added
