One Hat Cyber Team

View File Name : swagger.yaml

openapi: 3.0.3
info:
  title: B2C E-Commerce API
  description: |
    B2C E-Commerce REST API documentation.

    ## Authentication
    Most endpoints require a Bearer token for authentication. To obtain a token, use the `/api/v1/auth/login` endpoint.

    Include the token in the Authorization header:
    ```
    Authorization: Bearer {your_token}
    ```

  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://b2c-ecommerce.test:8080/api
    description: Local Development Server
  - url: https://ecommerce.dev-unit.com/api
    description: Production Server

tags:
  - name: Health
    description: API health check endpoints
  - name: Auth
    description: Authentication and authorization endpoints
  - name: User
    description: User profile and address management endpoints
  - name: Products
    description: Public product endpoints (no authentication required)
  - name: Categories
    description: Public category endpoints (no authentication required)
  - name: Cart
    description: Shopping cart endpoints (session-based, no authentication required)
  - name: Wishlist
    description: Wishlist management endpoints (authentication required)
  - name: Orders
    description: Order management endpoints (authentication required)

paths:
  /health:
    get:
      tags:
        - Health
      summary: Health Check
      description: Check if the API is running
      operationId: healthCheck
      responses:
        '200':
          description: API is running
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /v1/auth/register:
    post:
      tags:
        - Auth
      summary: Register User
      description: Create a new user account. An email verification token will be sent to the registered email.
      operationId: register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/RegisterRequestForm'
      responses:
        '201':
          description: Registration successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/auth/login:
    post:
      tags:
        - Auth
      summary: Login User
      description: Authenticate with email and password. Returns a Bearer token for subsequent requests.
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Email not verified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/auth/me:
    get:
      tags:
        - Auth
      summary: Get Current User
      description: Get the authenticated user's profile information.
      operationId: getCurrentUser
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User profile retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/auth/refresh:
    post:
      tags:
        - Auth
      summary: Refresh Token
      description: Generate a new access token (invalidates the current token).
      operationId: refreshToken
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshTokenResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/auth/logout:
    post:
      tags:
        - Auth
      summary: Logout
      description: Invalidate the current authentication token.
      operationId: logout
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Logged out successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /v1/auth/forgot-password:
    post:
      tags:
        - Auth
      summary: Forgot Password
      description: Request a password reset link to be sent to the user's email.
      operationId: forgotPassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForgotPasswordRequest'
      responses:
        '200':
          description: Reset link sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/auth/reset-password/{token}:
    post:
      tags:
        - Auth
      summary: Reset Password
      description: Reset the user's password using a reset token sent via email.
      operationId: resetPassword
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Password reset token received via email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordRequest'
      responses:
        '200':
          description: Password reset successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid or expired token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/auth/verify/{token}:
    get:
      tags:
        - Auth
      summary: Verify Email
      description: Verify the user's email address using the verification token.
      operationId: verifyEmail
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Email verification token
      responses:
        '200':
          description: Email verified successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyEmailResponse'
        '400':
          description: Invalid verification token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/auth/resend-verification:
    post:
      tags:
        - Auth
      summary: Resend Verification Email
      description: Resend the email verification link to the user.
      operationId: resendVerification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResendVerificationRequest'
      responses:
        '200':
          description: Verification email sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Email already verified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/user:
    get:
      tags:
        - User
      summary: Get User Profile
      description: Get the authenticated user's profile with complete details including address information and state.
      operationId: getUserProfile
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User profile retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/update-profile:
    post:
      tags:
        - User
      summary: Update User Profile
      description: Update the authenticated user's profile information. Supports updating name, phone, and avatar via file upload or URL.
      operationId: updateProfile
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProfileRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UpdateProfileRequestForm'
      responses:
        '200':
          description: Profile updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/get-countries:
    get:
      tags:
        - User
      summary: Get Countries
      description: Get list of all available countries.
      operationId: getCountries
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Countries retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Country'

  /v1/update-billing-address:
    post:
      tags:
        - User
      summary: Update Billing Address
      description: Update the authenticated user's billing address information.
      operationId: updateBillingAddress
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBillingAddressRequest'
      responses:
        '200':
          description: Billing address updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/update-shipping-address:
    post:
      tags:
        - User
      summary: Update Shipping Address
      description: Update the authenticated user's shipping address information.
      operationId: updateShippingAddress
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateShippingAddressRequest'
      responses:
        '200':
          description: Shipping address updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/products:
    get:
      tags:
        - Products
      summary: List Products
      description: Get paginated list of products with optional filters for category, brand, price range, and sorting options.
      operationId: listProducts
      parameters:
        - name: category_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by category ID
        - name: subcategory_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by subcategory ID
        - name: childcategory_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by childcategory ID
        - name: brand_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by brand ID
        - name: min_price
          in: query
          required: false
          schema:
            type: number
          description: Minimum price filter
        - name: max_price
          in: query
          required: false
          schema:
            type: number
          description: Maximum price filter
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum: [price_asc, price_desc, newest, popular, rating]
            default: newest
          description: Sort order
        - name: featured
          in: query
          required: false
          schema:
            type: boolean
          description: Filter by featured products only
        - name: status
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: Filter by active status
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 15
          description: Number of items per page
      responses:
        '200':
          description: Products retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/products/featured:
    get:
      tags:
        - Products
      summary: Featured Products
      description: Get paginated list of featured products.
      operationId: featuredProducts
      parameters:
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of items per page
      responses:
        '200':
          description: Featured products retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsResponse'

  /v1/products/latest:
    get:
      tags:
        - Products
      summary: Latest Products
      description: Get paginated list of latest products.
      operationId: latestProducts
      parameters:
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of items per page
      responses:
        '200':
          description: Latest products retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsResponse'

  /v1/products/search:
    get:
      tags:
        - Products
      summary: Search Products
      description: Search products by keyword in name, description, SKU, or tags.
      operationId: searchProducts
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 2
          description: Search query string
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 15
          description: Number of items per page
      responses:
        '200':
          description: Search results retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsSearchResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/products/{identifier}:
    get:
      tags:
        - Products
      summary: Get Product Details
      description: Get a single product by ID or slug with related products from the same category.
      operationId: getProduct
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
          description: Product ID or slug
      responses:
        '200':
          description: Product retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductDetailResponse'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/categories/{id}/products:
    get:
      tags:
        - Products
      summary: Products by Category
      description: Get paginated list of products for a specific category.
      operationId: productsByCategory
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Category ID
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 15
          description: Number of items per page
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum: [price_asc, price_desc, newest, popular]
            default: newest
          description: Sort order
      responses:
        '200':
          description: Category products retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryProductsResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/brands/{id}/products:
    get:
      tags:
        - Products
      summary: Products by Brand
      description: Get paginated list of products for a specific brand.
      operationId: productsByBrand
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Brand ID
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 15
          description: Number of items per page
      responses:
        '200':
          description: Brand products retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandProductsResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/categories:
    get:
      tags:
        - Categories
      summary: List Categories
      description: Get all categories with optional filters for featured and subcategories.
      operationId: listCategories
      parameters:
        - name: featured
          in: query
          required: false
          schema:
            type: boolean
          description: Filter by featured categories only
        - name: with_subcategories
          in: query
          required: false
          schema:
            type: boolean
          description: Include subcategories in response
        - name: with_products_count
          in: query
          required: false
          schema:
            type: boolean
          description: Include products count for each category
      responses:
        '200':
          description: Categories retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoriesResponse'

  /v1/categories/{identifier}:
    get:
      tags:
        - Categories
      summary: Get Category Details
      description: Get a single category by ID or slug with subcategories and products count.
      operationId: getCategory
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
          description: Category ID or slug
      responses:
        '200':
          description: Category retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponse'
        '404':
          description: Category not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/categories/{categoryId}/subcategories:
    get:
      tags:
        - Categories
      summary: Get Subcategories
      description: Get all subcategories for a specific category with product counts.
      operationId: getSubcategories
      parameters:
        - name: categoryId
          in: path
          required: true
          schema:
            type: integer
          description: Category ID
      responses:
        '200':
          description: Subcategories retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubcategoriesResponse'
        '404':
          description: Category not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/categories/subcategories/{subcategoryId}/childcategories:
    get:
      tags:
        - Categories
      summary: Get Child Categories
      description: Get all child categories for a specific subcategory with product counts.
      operationId: getChildcategories
      parameters:
        - name: subcategoryId
          in: path
          required: true
          schema:
            type: integer
          description: Subcategory ID
      responses:
        '200':
          description: Child categories retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChildcategoriesResponse'
        '404':
          description: Subcategory not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/cart:
    get:
      tags:
        - Cart
      summary: Get Cart
      description: Get current cart contents with item details and totals.
      operationId: getCart
      responses:
        '200':
          description: Cart retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartResponse'

  /v1/cart/count:
    get:
      tags:
        - Cart
      summary: Get Cart Count
      description: Get total number of items in cart.
      operationId: getCartCount
      responses:
        '200':
          description: Cart count retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartCountResponse'

  /v1/cart/add:
    post:
      tags:
        - Cart
      summary: Add to Cart
      description: Add a product to the cart with specified quantity.
      operationId: addToCart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddToCartRequest'
      responses:
        '200':
          description: Item added to cart successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartAddResponse'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Product out of stock
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/cart/update:
    post:
      tags:
        - Cart
      summary: Update Cart Item
      description: Update quantity of an item in the cart.
      operationId: updateCartItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCartItemRequest'
      responses:
        '200':
          description: Cart item updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '404':
          description: Cart item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Requested quantity exceeds available stock
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/cart/remove:
    post:
      tags:
        - Cart
      summary: Remove from Cart
      description: Remove an item from the cart.
      operationId: removeFromCart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveFromCartRequest'
      responses:
        '200':
          description: Item removed from cart successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '404':
          description: Cart item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/cart/clear:
    post:
      tags:
        - Cart
      summary: Clear Cart
      description: Remove all items from the cart.
      operationId: clearCart
      responses:
        '200':
          description: Cart cleared successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /v1/wishlist:
    get:
      tags:
        - Wishlist
      summary: Get Wishlist
      description: Get authenticated user's wishlist with product details.
      operationId: getWishlist
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Wishlist retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WishlistResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/wishlist/add:
    post:
      tags:
        - Wishlist
      summary: Add to Wishlist
      description: Add a product to the authenticated user's wishlist.
      operationId: addToWishlist
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddToWishlistRequest'
      responses:
        '201':
          description: Product added to wishlist successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Product already in wishlist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/wishlist/remove:
    post:
      tags:
        - Wishlist
      summary: Remove from Wishlist
      description: Remove a product from the authenticated user's wishlist.
      operationId: removeFromWishlist
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveFromWishlistRequest'
      responses:
        '200':
          description: Product removed from wishlist successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '404':
          description: Product not in wishlist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/wishlist/check/{productId}:
    get:
      tags:
        - Wishlist
      summary: Check Wishlist
      description: Check if a product is in the authenticated user's wishlist.
      operationId: checkWishlist
      security:
        - bearerAuth: []
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: integer
          description: Product ID
      responses:
        '200':
          description: Wishlist check completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WishlistCheckResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/wishlist/clear:
    post:
      tags:
        - Wishlist
      summary: Clear Wishlist
      description: Remove all products from the authenticated user's wishlist.
      operationId: clearWishlist
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Wishlist cleared successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /v1/orders:
    get:
      tags:
        - Orders
      summary: List Orders
      description: Get authenticated user's orders with optional status filter and pagination.
      operationId: listOrders
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [pending, processing, completed, cancelled, refunded]
          description: Filter by order status
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 15
          description: Number of items per page
      responses:
        '200':
          description: Orders retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/orders/store:
    post:
      tags:
        - Orders/store
      summary: Create Order
      description: Create a new order from cart with shipping and billing information.
      operationId: createOrder
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Product out of stock
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Failed to create order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/orders/{orderId}:
    get:
      tags:
        - Orders
      summary: Get Order Details
      description: Get details of a specific order including all items.
      operationId: getOrder
      security:
        - bearerAuth: []
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
          description: Order ID
      responses:
        '200':
          description: Order retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetailResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/orders/{orderId}/track:
    get:
      tags:
        - Orders
      summary: Track Order
      description: Get tracking history for a specific order.
      operationId: trackOrder
      security:
        - bearerAuth: []
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
          description: Order ID
      responses:
        '200':
          description: Order tracking retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderTrackingResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/orders/{orderId}/cancel:
    post:
      tags:
        - Orders
      summary: Cancel Order
      description: Cancel a pending or processing order.
      operationId: cancelOrder
      security:
        - bearerAuth: []
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
          description: Order ID
      responses:
        '200':
          description: Order cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Cannot cancel this order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from login endpoint

  schemas:
    # Health
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        message:
          type: string
          example: API is running
        timestamp:
          type: string
          format: date-time
          example: '2024-02-16T12:00:00.000000Z'

    # Auth - Register
    RegisterRequest:
      type: object
      required:
        - first_name
        - last_name
        - email
        - phone
        - password
        - password_confirmation
      properties:
        first_name:
          type: string
          maxLength: 255
          example: John
        last_name:
          type: string
          maxLength: 255
          example: Doe
        email:
          type: string
          format: email
          example: john.doe@example.com
        phone:
          type: string
          maxLength: 255
          example: '+1234567890'
        password:
          type: string
          minLength: 6
          example: password123
        password_confirmation:
          type: string
          minLength: 6
          example: password123
        

    RegisterRequestForm:
      type: object
      required:
        - first_name
        - last_name
        - email
        - phone
        - password
        - password_confirmation
      properties:
        first_name:
          type: string
          maxLength: 255
        last_name:
          type: string
          maxLength: 255
        email:
          type: string
          format: email
        phone:
          type: string
          maxLength: 255
        password:
          type: string
          minLength: 6
        password_confirmation:
          type: string
          minLength: 6
        

    RegisterResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Registration successful. Please verify your email to login.
        data:
          $ref: '#/components/schemas/AuthData'

    # Auth - Login
    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          example: john.doe@example.com
        password:
          type: string
          example: password123
        

    LoginResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Login successful.
        data:
          $ref: '#/components/schemas/AuthData'

    AuthData:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
        token:
          type: string
          example: '1|abc123xyz...'
        token_type:
          type: string
          example: Bearer

    # Auth - Refresh Token
    RefreshTokenResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Token refreshed successfully.
        data:
          type: object
          properties:
            token:
              type: string
              example: '2|xyz456abc...'
            token_type:
              type: string
              example: Bearer

    # Auth - Forgot Password
    ForgotPasswordRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          example: john.doe@example.com

    # Auth - Reset Password
    ResetPasswordRequest:
      type: object
      required:
        - password
        - password_confirmation
      properties:
        password:
          type: string
          minLength: 6
          example: newpassword123
        password_confirmation:
          type: string
          minLength: 6
          example: newpassword123

    # Auth - Resend Verification
    ResendVerificationRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          example: john.doe@example.com

    # Auth - Verify Email
    VerifyEmailResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Email verified successfully. You can now login.
        data:
          type: object
          properties:
            user:
              $ref: '#/components/schemas/User'

    # Common Response
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Operation successful.

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: The given data was invalid.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            email:
              - The email has already been taken.
            password:
              - The password confirmation does not match.

    # User
    UserResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            user:
              $ref: '#/components/schemas/User'

    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe
        full_name:
          type: string
          example: John Doe
        email:
          type: string
          format: email
          example: john.doe@example.com
        phone:
          type: string
          example: '+1234567890'
        photo:
          type: string
          format: uri
          nullable: true
          example: 'https://your-domain.com/storage/avatars/user_1.jpg'
        is_verified:
          type: boolean
          example: true
        addresses:
          $ref: '#/components/schemas/UserAddresses'
        created_at:
          type: string
          format: date-time
          example: '2024-01-01T10:00:00.000000Z'
        updated_at:
          type: string
          format: date-time
          example: '2024-02-16T15:30:00.000000Z'

    UserAddresses:
      type: object
      properties:
        shipping:
          $ref: '#/components/schemas/Address'
        billing:
          $ref: '#/components/schemas/BillingAddress'

    Address:
      type: object
      properties:
        address1:
          type: string
          nullable: true
          example: '123 Main St'
        address2:
          type: string
          nullable: true
          example: 'Apt 4B'
        city:
          type: string
          nullable: true
          example: New York
        country:
          type: string
          nullable: true
          example: USA
        zip:
          type: string
          nullable: true
          example: '10001'
        company:
          type: string
          nullable: true
          example: Acme Corp
        state_id:
          type: integer
          nullable: true
          example: 1

    BillingAddress:
      type: object
      properties:
        address1:
          type: string
          nullable: true
          example: '123 Main St'
        address2:
          type: string
          nullable: true
          example: 'Apt 4B'
        city:
          type: string
          nullable: true
          example: New York
        country:
          type: string
          nullable: true
          example: USA
        zip:
          type: string
          nullable: true
          example: '10001'
        company:
          type: string
          nullable: true
          example: Acme Corp

    # Update Profile
    UpdateProfileRequest:
      type: object
      properties:
        first_name:
          type: string
          maxLength: 255
          example: John
        last_name:
          type: string
          maxLength: 255
          example: Smith
        phone:
          type: string
          maxLength: 255
          example: '+1987654321'
        avatar_url:
          type: string
          maxLength: 500
          format: uri
          example: 'https://example.com/images/new-avatar.jpg'

    UpdateProfileRequestForm:
      type: object
      properties:
        first_name:
          type: string
          maxLength: 255
        last_name:
          type: string
          maxLength: 255
        phone:
          type: string
          maxLength: 255
        avatar:
          type: string
          format: binary
          description: Profile image file (jpeg, jpg, png, gif, max 2MB)

    # Country
    Country:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: United States

    # Update Billing Address
    UpdateBillingAddressRequest:
      type: object
      required:
        - bill_address1
        - bill_city
        - bill_country
      properties:
        bill_address1:
          type: string
          maxLength: 100
          example: '123 Main St'
        bill_address2:
          type: string
          maxLength: 100
          nullable: true
          example: 'Apt 4B'
        bill_zip:
          type: string
          maxLength: 100
          nullable: true
          example: '10001'
        bill_city:
          type: string
          maxLength: 100
          example: New York
        bill_company:
          type: string
          maxLength: 100
          nullable: true
          example: Acme Corp
        bill_country:
          type: string
          maxLength: 100
          example: USA

    # Update Shipping Address
    UpdateShippingAddressRequest:
      type: object
      required:
        - ship_address1
        - ship_city
        - ship_country
      properties:
        ship_address1:
          type: string
          maxLength: 100
          example: '456 Oak St'
        ship_address2:
          type: string
          maxLength: 100
          nullable: true
          example: 'Suite 100'
        ship_zip:
          type: string
          maxLength: 100
          nullable: true
          example: '10002'
        ship_city:
          type: string
          maxLength: 100
          example: Los Angeles
        ship_company:
          type: string
          maxLength: 100
          nullable: true
          example: Tech Corp
        ship_country:
          type: string
          maxLength: 100
          example: USA

    # State
    State:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: California
        country_id:
          type: integer
          example: 1

    # Products - Pagination
    Pagination:
      type: object
      properties:
        total:
          type: integer
          example: 100
          description: Total number of items
        per_page:
          type: integer
          example: 15
          description: Items per page
        current_page:
          type: integer
          example: 1
          description: Current page number
        last_page:
          type: integer
          example: 7
          description: Last page number
        from:
          type: integer
          example: 1
          description: First item number
        to:
          type: integer
          example: 15
          description: Last item number
        has_more_pages:
          type: boolean
          example: true
          description: Whether there are more pages

    # Products - Basic
    Product:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 'Wireless Bluetooth Headphones'
        slug:
          type: string
          example: 'wireless-bluetooth-headphones'
        sku:
          type: string
          example: 'WBH-001'
        description:
          type: string
          example: 'High-quality wireless headphones with noise cancellation...'
        short_description:
          type: string
          example: 'Premium wireless headphones'
        tags:
          type: string
          nullable: true
          example: 'wireless, bluetooth, headphones'
        video:
          type: string
          format: uri
          nullable: true
        item_type:
          type: string
          enum: [normal, digital, license, affiliate]
          example: normal
        stock:
          type: integer
          example: 50
        in_stock:
          type: boolean
          example: true
        status:
          type: integer
          example: 1
        featured:
          type: integer
          example: 0
        affiliate_link:
          type: string
          format: uri
          nullable: true
        file_type:
          type: string
          nullable: true
        price:
          $ref: '#/components/schemas/ProductPrice'
        images:
          $ref: '#/components/schemas/ProductImages'
        category:
          $ref: '#/components/schemas/Category'
        subcategory:
          $ref: '#/components/schemas/Subcategory'
        childcategory:
          $ref: '#/components/schemas/Childcategory'
        brand:
          $ref: '#/components/schemas/Brand'
        tax:
          $ref: '#/components/schemas/ProductTax'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/ProductAttribute'
        specifications:
          $ref: '#/components/schemas/ProductSpecifications'
        seo:
          $ref: '#/components/schemas/ProductSEO'
        ratings:
          $ref: '#/components/schemas/ProductRatings'
        created_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00.000000Z'
        updated_at:
          type: string
          format: date-time
          example: '2024-02-20T14:25:00.000000Z'

    ProductPrice:
      type: object
      properties:
        current:
          type: number
          format: float
          example: 99.99
        previous:
          type: number
          format: float
          example: 129.99
        discount_percentage:
          type: number
          format: float
          example: 23.08

    ProductImages:
      type: object
      properties:
        main:
          type: string
          format: uri
          nullable: true
          example: 'https://your-domain.com/assets/images/products/headphone.jpg'
        thumbnail:
          type: string
          format: uri
          nullable: true
          example: 'https://your-domain.com/assets/images/thumbnails/headphone.jpg'
        gallery:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              image:
                type: string
                format: uri
                example: 'https://your-domain.com/assets/images/products/gallery1.jpg'

    Category:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Electronics
        slug:
          type: string
          example: electronics
        photo:
          type: string
          format: uri
          nullable: true
          example: 'https://your-domain.com/assets/images/categories/electronics.jpg'

    Subcategory:
      type: object
      properties:
        id:
          type: integer
          nullable: true
        name:
          type: string
          nullable: true
          example: Audio
        slug:
          type: string
          nullable: true
          example: audio

    Childcategory:
      type: object
      properties:
        id:
          type: integer
          nullable: true
        name:
          type: string
          nullable: true
          example: Headphones
        slug:
          type: string
          nullable: true
          example: headphones

    Brand:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Sony
        slug:
          type: string
          example: sony
        photo:
          type: string
          format: uri
          nullable: true
          example: 'https://your-domain.com/assets/images/brands/sony.jpg'
        is_popular:
          type: boolean
          example: true

    ProductTax:
      type: object
      nullable: true
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: VAT
        value:
          type: number
          format: float
          example: 10
        tax_amount:
          type: number
          format: float
          example: 10.00

    ProductAttribute:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Color
        keyword:
          type: string
          example: color
        options:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: Black
              price:
                type: number
                format: float
                example: 0

    ProductSpecifications:
      type: object
      nullable: true
      properties:
        name:
          type: string
          example: Technical Specifications
        description:
          type: string
          example: 'Bluetooth 5.0, 30h battery life...'

    ProductSEO:
      type: object
      properties:
        meta_keywords:
          type: string
          nullable: true
          example: 'wireless, headphones, bluetooth, audio'
        meta_description:
          type: string
          nullable: true
          example: 'Premium wireless headphones with noise cancellation'

    ProductRatings:
      type: object
      properties:
        average:
          type: number
          format: float
          example: 4.5
        count:
          type: integer
          example: 128
        percentage:
          type: number
          format: float
          example: 90

    # Products - Response Schemas
    ProductsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Products retrieved successfully.
        data:
          type: object
          properties:
            products:
              type: array
              items:
                $ref: '#/components/schemas/Product'
            pagination:
              $ref: '#/components/schemas/Pagination'

    ProductsSearchResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Search results retrieved successfully.
        data:
          type: object
          properties:
            query:
              type: string
              example: headphones
            products:
              type: array
              items:
                $ref: '#/components/schemas/Product'
            pagination:
              $ref: '#/components/schemas/Pagination'

    ProductDetailResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Product retrieved successfully.
        data:
          type: object
          properties:
            product:
              $ref: '#/components/schemas/Product'
            related_products:
              type: array
              items:
                $ref: '#/components/schemas/Product'

    CategoryProductsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Category products retrieved successfully.
        data:
          type: object
          properties:
            category:
              $ref: '#/components/schemas/Category'
            products:
              type: array
              items:
                $ref: '#/components/schemas/Product'
            pagination:
              $ref: '#/components/schemas/Pagination'

    BrandProductsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Brand products retrieved successfully.
        data:
          type: object
          properties:
            brand:
              $ref: '#/components/schemas/Brand'
            products:
              type: array
              items:
                $ref: '#/components/schemas/Product'
            pagination:
              $ref: '#/components/schemas/Pagination'