swagger.yaml

openapi: 3.0.0
info:
  title: Trippz API
  description: |
    API documentation for the Trippz travel application.

    This API provides endpoints for managing users, destinations, bookings, payments, and more.

    ## Authentication
    Most endpoints require authentication using JSON Web Tokens (JWT).

    ### How to Authenticate:
    1. Register or log in to obtain your access and refresh tokens.
    2. Include your access token in requests using **one of the following methods**:
      - **Custom Headers:**  
        `x-trippz-access-token: <access-token>`  
        `x-trippz-refresh-token: <refresh-token>`
      - **Cookies (for web clients):**  
        Send `accessToken` and `refreshToken` cookies.  
        (Use `withCredentials: true` when making requests from browsers.)

    ### Important Notes:
    - Access tokens authenticate user requests.
    - Refresh tokens are used to silently renew expired sessions without re-login.
    - Tokens sent via custom headers are preferred for mobile clients and APIs.
    - Tokens sent via cookies are primarily used for web browser sessions.

     ## Rate Limiting
     All API requests are limited to **100 requests per minute** per IP address.

  ## Versioning
  version: 1.0.0
  contact:
    email: support@trippz.com

servers:
  - url: https://trippz.onrender.com/api/v1
    description: Testing server

  - url: https://api.travelapp.com/api/v1
    description: Production server

  - url: http://localhost:5000/api/v1
    description: Development server

components:
  securitySchemes:
    TrippzHeaderAuth:
      type: apiKey
      in: header
      name: x-trippz-access-token
      description: |
        Access token in custom header.

    TrippzRefreshTokenHeader:
      type: apiKey
      in: header
      name: x-trippz-refresh-token
      description: |
        Refresh token in custom header. Used to obtain a  access token when expired.

    CookieAccessToken:
      type: apiKey
      in: cookie
      name: accessToken
      description: |
        Access token stored in cookie. Fallback for browser clients. Automatically refreshed when  expired if refresh token is present.

    CookieRefreshToken:
      type: apiKey
      in: cookie
      name: refreshToken
      description: |
        Refresh token stored in cookie. Used to obtain a new access token when expired.

  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        first_name:
          type: string
          example: "Asikur"
        last_name:
          type: string
          example: "Rahman"
        email:
          type: string
          format: email
          example: "asikurrahaman997@gmail.com"
        phone_number:
          type: string
          example: "+8801712345678"
        role:
          type: string
          enum: [USER, SERVICE_PROVIDER, TRAVEL_AGENCY, ADMIN]
          example: "USER"
        email_verified:
          type: boolean
          example: false
        phone_verified:
          type: boolean
          example: false
        profile_picture:
          type: string
          nullable: true
          example: "https://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg"
        created_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"

    RegisterInput:
      type: object
      required:
        - first_name
        - last_name
        - email
        - password
      properties:
        first_name:
          type: string
          minLength: 2
          example: "Asikur"
          default: "Asikur"
        last_name:
          type: string
          minLength: 2
          example: "Rahman"
          default: "Rahman"
        email:
          type: string
          format: email
          example: "asikurrahaman997@gmail.com"
          default: "asikurrahaman997@gmail.com"
        phone_number:
          type: string
          minLength: 10
          example: "+8801712345678"
          default: "+8801712345678"
        password:
          type: string
          minLength: 8
          example: "12345678"
          default: "12345678"
        role:
          type: string
          enum: [USER, SERVICE_PROVIDER, TRAVEL_AGENCY]
          example: "USER"
          default: USER
        date_of_birth:
          type: string
          format: date
          nullable: true
          example: "1990-01-01"
          default: "1990-01-01"
        address:
          type: string
          nullable: true
          example: "123 Main St, Dhaka, Bangladesh"
          default: "123 Main St, Dhaka, Bangladesh"

    LoginInput:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          example: "asikurrahaman997@gmail.com"
          default: "asikurrahaman997@gmail.com"
        password:
          type: string
          example: "12345678"
          default: "12345678"

    ForgotPasswordInput:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          example: "asikurrahaman997@gmail.com"
          default: "asikurrahaman997@gmail.com"

    ResetPasswordInput:
      type: object
      required:
        - token
        - password
        - confirm_password
      properties:
        token:
          type: string
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
          default: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        password:
          type: string
          minLength: 8
          example: "newpassword123"
          default: "newpassword123"
        confirm_password:
          type: string
          example: "newpassword123"
          default: "newpassword123"

    VerifyEmailInput:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
          default: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

    VerifyPhoneInput:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          minLength: 6
          maxLength: 6
          example: "123456"
          default: "123456"

    RefreshTokenInput:
      type: object
      required:
        - refreshToken
      properties:
        refreshToken:
          type: string
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
          default: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

    LogoutInput:
      type: object
      required:
        - refreshToken
      properties:
        refreshToken:
          type: string
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
          default: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

    CreateFlightInput:
      type: object
      required:
        - flight_number
        - airline
        - departure_time
        - arrival_time
        - from_airport
        - to_airport
        - price
        - seat_class
      properties:
        flight_number:
          type: string
          example: "BA123"
          default: "BA123"
        airline:
          type: string
          example: "British Airways"
          default: "British Airways"
        departure_time:
          type: string
          format: date-time
          example: "2023-12-01T10:00:00Z"
          default: "2023-12-01T10:00:00Z"
        arrival_time:
          type: string
          format: date-time
          example: "2023-12-01T14:00:00Z"
          default: "2023-12-01T14:00:00Z"
        from_airport:
          type: string
          example: "LHR"
          default: "LHR"
        to_airport:
          type: string
          example: "JFK"
          default: "JFK"
        price:
          type: number
          format: float
          example: 499.99
          default: 499.99
        seat_class:
          type: string
          example: "Economy"
          default: "Economy"
        available_seats:
          type: integer
          example: 150
          default: 150
        aircraft_type:
          type: string
          example: "Boeing 787"
          default: "Boeing 787"
        has_wifi:
          type: boolean
          example: true
          default: true
        has_entertainment:
          type: boolean
          example: true
          default: true
        has_power_outlets:
          type: boolean
          example: true
          default: true
        meal_service:
          type: boolean
          example: true
          default: true
        baggage_allowance:
          type: integer
          example: 2
          default: 2
        cancellation_policy:
          type: string
          example: "Free cancellation up to 24 hours before departure"
          default: "Free cancellation up to 24 hours before departure"

    UpdateFlightInput:
      type: object
      properties:
        flight_number:
          type: string
          example: "BA456"
          default: "BA456"
        airline:
          type: string
          example: "British Airways"
          default: "British Airways"
        departure_time:
          type: string
          format: date-time
          example: "2023-12-01T11:00:00Z"
          default: "2023-12-01T11:00:00Z"
        arrival_time:
          type: string
          format: date-time
          example: "2023-12-01T15:00:00Z"
          default: "2023-12-01T15:00:00Z"
        from_airport:
          type: string
          example: "LHR"
          default: "LHR"
        to_airport:
          type: string
          example: "JFK"
          default: "JFK"
        price:
          type: number
          format: float
          example: 549.99
          default: 549.99
        seat_class:
          type: string
          example: "Business"
          default: "Business"
        available_seats:
          type: integer
          example: 50
          default: 50
        aircraft_type:
          type: string
          example: "Airbus A380"
          default: "Airbus A380"
        has_wifi:
          type: boolean
          example: true
          default: true
        has_entertainment:
          type: boolean
          example: true
          default: true
        has_power_outlets:
          type: boolean
          example: true
          default: true
        meal_service:
          type: boolean
          example: true
          default: true
        baggage_allowance:
          type: integer
          example: 3
          default: 3
        cancellation_policy:
          type: string
          example: "Free cancellation up to 48 hours before departure"
          default: "Free cancellation up to 48 hours before departure"

    SearchFlightsInput:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
          example: 1
          default: 1
        limit:
          type: integer
          minimum: 1
          maximum: 100
          example: 20
          default: 20
        sortBy:
          type: string
          enum: [departure_time, arrival_time, price, airline, created_at]
          example: "departure_time"
          default: "departure_time"
        sortOrder:
          type: string
          enum: [asc, desc]
          example: "asc"
          default: "asc"
        from:
          type: string
          example: "LHR"
        to:
          type: string
          example: "JFK"
        departure_date:
          type: string
          format: date
          example: "2023-12-01"
        return_date:
          type: string
          format: date
          example: "2023-12-15"
        seat_class:
          type: string
          example: "Economy"
        minPrice:
          type: number
          example: 300
        maxPrice:
          type: number
          example: 1000
        airline:
          type: string
          example: "British Airways"
        direct_flights_only:
          type: boolean
          example: true
        has_wifi:
          type: boolean
          example: true
        has_entertainment:
          type: boolean
          example: true
        has_power_outlets:
          type: boolean
          example: true
        meal_service:
          type: boolean
          example: true
        min_baggage_allowance:
          type: integer
          example: 2

    FlightAvailabilityInput:
      type: object
      required:
        - flight_id
      properties:
        flight_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        date:
          type: string
          format: date
          example: "2023-12-01"
        passengers:
          type: integer
          minimum: 1
          example: 2
          default: 1

    CreateHotelInput:
      type: object
      required:
        - name
        - address
        - price_per_night
        - available_rooms
      properties:
        name:
          type: string
          example: "Marriott Hotel"
          default: "Marriott Hotel"
        address:
          type: string
          example: "123 Main St, New York, NY"
          default: "123 Main St, New York, NY"
        rating:
          type: number
          format: float
          minimum: 0
          maximum: 5
          example: 4.5
          default: 4.5
        price_per_night:
          type: number
          format: float
          example: 199.99
          default: 199.99
        amenities:
          type: array
          items:
            type: string
          example: ["WiFi", "Pool", "Gym", "Restaurant"]
          default: ["WiFi", "Pool", "Gym", "Restaurant"]
        available_rooms:
          type: integer
          example: 10
          default: 10
        description:
          type: string
          example: "A luxurious hotel in the heart of the city with modern amenities and exceptional service."
          default: "A luxurious hotel in the heart of the city with modern amenities and exceptional service."
        check_in_time:
          type: string
          example: "14:00"
          default: "14:00"
        check_out_time:
          type: string
          example: "12:00"
          default: "12:00"
        location:
          type: object
          properties:
            latitude:
              type: number
              format: float
              example: 40.7128
            longitude:
              type: number
              format: float
              example: -74.0060
            city:
              type: string
              example: "New York"
            country:
              type: string
              example: "USA"
        property_type:
          type: string
          example: "Hotel"
          default: "Hotel"
        has_free_cancellation:
          type: boolean
          example: true
          default: true
        has_breakfast_included:
          type: boolean
          example: true
          default: true
        has_parking:
          type: boolean
          example: true
          default: true
        has_pool:
          type: boolean
          example: true
          default: true
        has_gym:
          type: boolean
          example: true
          default: true
        has_restaurant:
          type: boolean
          example: true
          default: true
        has_room_service:
          type: boolean
          example: true
          default: true
        has_spa:
          type: boolean
          example: true
          default: true
        has_wifi:
          type: boolean
          example: true
          default: true
        has_air_conditioning:
          type: boolean
          example: true
          default: true
        is_pet_friendly:
          type: boolean
          example: false
          default: false
        is_family_friendly:
          type: boolean
          example: true
          default: true

    UpdateHotelInput:
      type: object
      properties:
        name:
          type: string
          example: "Marriott Grand Hotel"
          default: "Marriott Grand Hotel"
        address:
          type: string
          example: "123 Main St, New York, NY"
          default: "123 Main St, New York, NY"
        rating:
          type: number
          format: float
          minimum: 0
          maximum: 5
          example: 4.8
          default: 4.8
        price_per_night:
          type: number
          format: float
          example: 249.99
          default: 249.99
        amenities:
          type: array
          items:
            type: string
          example: ["WiFi", "Pool", "Gym", "Restaurant", "Spa"]
          default: ["WiFi", "Pool", "Gym", "Restaurant", "Spa"]
        available_rooms:
          type: integer
          example: 15
          default: 15
        description:
          type: string
          example: "A luxurious hotel in the heart of the city with modern amenities and exceptional service."
          default: "A luxurious hotel in the heart of the city with modern amenities and exceptional service."
        check_in_time:
          type: string
          example: "15:00"
          default: "15:00"
        check_out_time:
          type: string
          example: "11:00"
          default: "11:00"
        location:
          type: object
          properties:
            latitude:
              type: number
              format: float
              example: 40.7128
            longitude:
              type: number
              format: float
              example: -74.0060
            city:
              type: string
              example: "New York"
            country:
              type: string
              example: "USA"
        property_type:
          type: string
          example: "Resort"
          default: "Resort"
        has_free_cancellation:
          type: boolean
          example: true
          default: true
        has_breakfast_included:
          type: boolean
          example: true
          default: true
        has_parking:
          type: boolean
          example: true
          default: true
        has_pool:
          type: boolean
          example: true
          default: true
        has_gym:
          type: boolean
          example: true
          default: true
        has_restaurant:
          type: boolean
          example: true
          default: true
        has_room_service:
          type: boolean
          example: true
          default: true
        has_spa:
          type: boolean
          example: true
          default: true
        has_wifi:
          type: boolean
          example: true
          default: true
        has_air_conditioning:
          type: boolean
          example: true
          default: true
        is_pet_friendly:
          type: boolean
          example: true
          default: true
        is_family_friendly:
          type: boolean
          example: true
          default: true

    SearchHotelsInput:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
          example: 1
          default: 1
        limit:
          type: integer
          minimum: 1
          maximum: 100
          example: 20
          default: 20
        sortBy:
          type: string
          enum: [created_at, price_per_night, rating, name]
          example: "price_per_night"
          default: "created_at"
        sortOrder:
          type: string
          enum: [asc, desc]
          example: "asc"
          default: "desc"
        location:
          type: string
          example: "New York"
        city:
          type: string
          example: "New York"
        country:
          type: string
          example: "USA"
        check_in:
          type: string
          format: date
          example: "2023-12-01"
        check_out:
          type: string
          format: date
          example: "2023-12-05"
        guests:
          type: integer
          minimum: 1
          example: 2
        rooms:
          type: integer
          minimum: 1
          example: 1
        minPrice:
          type: number
          example: 100
        maxPrice:
          type: number
          example: 500
        rating:
          type: number
          minimum: 0
          maximum: 5
          example: 4
        amenities:
          type: array
          items:
            type: string
          example: ["WiFi", "Pool", "Gym"]
        distance_from_center:
          type: number
          example: 2
        has_free_cancellation:
          type: boolean
          example: true
        has_breakfast_included:
          type: boolean
          example: true
        has_parking:
          type: boolean
          example: true
        has_pool:
          type: boolean
          example: true
        has_gym:
          type: boolean
          example: true
        has_restaurant:
          type: boolean
          example: true
        has_room_service:
          type: boolean
          example: true
        has_spa:
          type: boolean
          example: true
        has_wifi:
          type: boolean
          example: true
        has_air_conditioning:
          type: boolean
          example: true
        is_pet_friendly:
          type: boolean
          example: true
        is_family_friendly:
          type: boolean
          example: true

    HotelAvailabilityInput:
      type: object
      required:
        - hotel_id
        - check_in
        - check_out
      properties:
        hotel_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        check_in:
          type: string
          format: date
          example: "2023-12-01"
        check_out:
          type: string
          format: date
          example: "2023-12-05"
        guests:
          type: integer
          minimum: 1
          example: 2
          default: 1
        rooms:
          type: integer
          minimum: 1
          example: 1
          default: 1

    CreateTripInput:
      type: object
      required:
        - trip_name
        - description
        - start_date
        - end_date
        - trip_type
        - price
      properties:
        trip_name:
          type: string
          example: "European Adventure"
          default: "European Adventure"
        description:
          type: string
          example: "Explore the best of Europe with our comprehensive tour package."
          default: "Explore the best of Europe with our comprehensive tour package."
        start_date:
          type: string
          format: date
          example: "2023-12-01"
          default: "2023-12-01"
        end_date:
          type: string
          format: date
          example: "2023-12-15"
          default: "2023-12-15"
        trip_type:
          type: string
          enum: [ADVENTURE, MEDICAL, BUSINESS, LEISURE]
          example: "ADVENTURE"
          default: "ADVENTURE"
        price:
          type: number
          format: float
          example: 1999.99
          default: 1999.99
        max_participants:
          type: integer
          example: 20
          default: 20
        destination_ids:
          type: array
          items:
            type: string
            format: uuid
          example:
            [
              "123e4567-e89b-12d3-a456-426614174000",
              "123e4567-e89b-12d3-a456-426614174001",
            ]
        itinerary:
          type: object
          example:
            {
              "day1": "Arrival in Paris, welcome dinner",
              "day2": "Eiffel Tower and Louvre Museum tour",
              "day3": "Travel to Amsterdam by train",
            }
        inclusions:
          type: array
          items:
            type: string
          example:
            [
              "Accommodation",
              "Breakfast",
              "Local guides",
              "Transportation between cities",
            ]
        exclusions:
          type: array
          items:
            type: string
          example: ["Flights to/from Europe", "Travel insurance", "Personal expenses"]
        cancellation_policy:
          type: string
          example: "Full refund if cancelled 30 days before departure"
        difficulty_level:
          type: string
          example: "Moderate"
        is_guided:
          type: boolean
          example: true
        is_family_friendly:
          type: boolean
          example: true
        is_accessible:
          type: boolean
          example: false
        includes_flight:
          type: boolean
          example: false
        includes_hotel:
          type: boolean
          example: true
        includes_activities:
          type: boolean
          example: true
        includes_meals:
          type: boolean
          example: true
        travel_style:
          type: string
          example: "Cultural"
        theme:
          type: string
          example: "History & Culture"

    UpdateTripInput:
      type: object
      properties:
        trip_name:
          type: string
          example: "European Adventure Deluxe"
          default: "European Adventure Deluxe"
        description:
          type: string
          example: "Explore the best of Europe with our comprehensive luxury tour package."
          default: "Explore the best of Europe with our comprehensive luxury tour package."
        start_date:
          type: string
          format: date
          example: "2023-12-05"
          default: "2023-12-05"
        end_date:
          type: string
          format: date
          example: "2023-12-20"
          default: "2023-12-20"
        trip_type:
          type: string
          enum: [ADVENTURE, MEDICAL, BUSINESS, LEISURE]
          example: "LEISURE"
          default: "LEISURE"
        price:
          type: number
          format: float
          example: 2499.99
          default: 2499.99
        max_participants:
          type: integer
          example: 15
          default: 15
        destination_ids:
          type: array
          items:
            type: string
            format: uuid
          example:
            [
              "123e4567-e89b-12d3-a456-426614174000",
              "123e4567-e89b-12d3-a456-426614174001",
              "123e4567-e89b-12d3-a456-426614174002",
            ]
        itinerary:
          type: object
          example:
            {
              "day1": "Arrival in Paris, luxury welcome dinner",
              "day2": "Private Eiffel Tower and Louvre Museum tour",
              "day3": "First-class train to Amsterdam",
            }
        inclusions:
          type: array
          items:
            type: string
          example:
            [
              "Luxury Accommodation",
              "All Meals",
              "Private guides",
              "First-class transportation",
            ]
        exclusions:
          type: array
          items:
            type: string
          example: ["Flights to/from Europe", "Travel insurance", "Personal expenses"]
        cancellation_policy:
          type: string
          example: "Full refund if cancelled 45 days before departure"
        difficulty_level:
          type: string
          example: "Easy"
        is_guided:
          type: boolean
          example: true
        is_family_friendly:
          type: boolean
          example: true
        is_accessible:
          type: boolean
          example: true
        includes_flight:
          type: boolean
          example: false
        includes_hotel:
          type: boolean
          example: true
        includes_activities:
          type: boolean
          example: true
        includes_meals:
          type: boolean
          example: true
        travel_style:
          type: string
          example: "Luxury"
        theme:
          type: string
          example: "History & Culture"

    SearchTripsInput:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
          example: 1
          default: 1
        limit:
          type: integer
          minimum: 1
          maximum: 100
          example: 20
          default: 20
        sortBy:
          type: string
          enum: [created_at, start_date, end_date, price, trip_name]
          example: "start_date"
          default: "created_at"
        sortOrder:
          type: string
          enum: [asc, desc]
          example: "asc"
          default: "desc"
        trip_type:
          type: string
          enum: [ADVENTURE, MEDICAL, BUSINESS, LEISURE]
          example: "ADVENTURE"
        destination:
          type: string
          example: "Paris"
        start_date:
          type: string
          format: date
          example: "2023-12-01"
        end_date:
          type: string
          format: date
          example: "2023-12-31"
        minPrice:
          type: number
          example: 1000
        maxPrice:
          type: number
          example: 3000
        duration_min:
          type: integer
          example: 7
        duration_max:
          type: integer
          example: 14
        min_rating:
          type: number
          minimum: 0
          maximum: 5
          example: 4
        max_participants:
          type: integer
          example: 20
        has_availability:
          type: boolean
          example: true
        includes_flight:
          type: boolean
          example: false
        includes_hotel:
          type: boolean
          example: true
        includes_activities:
          type: boolean
          example: true
        includes_meals:
          type: boolean
          example: true
        is_guided:
          type: boolean
          example: true
        is_family_friendly:
          type: boolean
          example: true
        is_accessible:
          type: boolean
          example: false
        has_free_cancellation:
          type: boolean
          example: true

    TripAvailabilityInput:
      type: object
      required:
        - trip_id
        - start_date
        - end_date
      properties:
        trip_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        start_date:
          type: string
          format: date
          example: "2023-12-01"
        end_date:
          type: string
          format: date
          example: "2023-12-15"
        participants:
          type: integer
          minimum: 1
          example: 2
          default: 1

    Booking:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        user_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174001"
        booking_type:
          type: string
          enum: [FLIGHT, HOTEL, TRIP]
          example: "HOTEL"
        start_date:
          type: string
          format: date
          example: "2023-12-01"
        end_date:
          type: string
          format: date
          example: "2023-12-05"
        status:
          type: string
          enum: [PENDING, CONFIRMED, CANCELED, COMPLETED]
          example: "CONFIRMED"
        total_price:
          type: number
          format: float
          example: 799.96
        flight_id:
          type: string
          format: uuid
          nullable: true
          example: null
        hotel_id:
          type: string
          format: uuid
          nullable: true
          example: "123e4567-e89b-12d3-a456-426614174002"
        trip_id:
          type: string
          format: uuid
          nullable: true
          example: null
        created_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"

    Payment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        booking_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174001"
        payment_method:
          type: string
          enum: [CREDIT_CARD, PAYPAL, GOOGLE_PAY, APPLE_PAY]
          example: "CREDIT_CARD"
        amount_paid:
          type: number
          format: float
          example: 799.96
        payment_status:
          type: string
          enum: [PENDING, SUCCESS, FAILED, REFUNDED]
          example: "SUCCESS"
        payment_date:
          type: string
          format: date-time
          example: "2023-11-25T14:30:00Z"
        payment_details:
          $ref: "#/components/schemas/PaymentDetail"
        created_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"

    PaymentDetail:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        transaction_id:
          type: string
          example: "txn_1234567890"
        provider:
          type: string
          example: "Stripe"
        refund_id:
          type: string
          nullable: true
          example: null

    Review:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        user_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174001"
        hotel_id:
          type: string
          format: uuid
          nullable: true
          example: "123e4567-e89b-12d3-a456-426614174002"
        flight_id:
          type: string
          format: uuid
          nullable: true
          example: null
        trip_id:
          type: string
          format: uuid
          nullable: true
          example: null
        rating:
          type: number
          format: float
          minimum: 1
          maximum: 5
          example: 4.5
        comment:
          type: string
          nullable: true
          example: "Great experience! Would definitely recommend."
        user:
          $ref: "#/components/schemas/User"
        created_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"

    Image:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        file_url:
          type: string
          example: "https://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg"
        file_type:
          type: string
          example: "image/jpeg"
        is_featured:
          type: boolean
          example: true
        alt_text:
          type: string
          example: "Paris Eiffel Tower"
        position:
          type: integer
          example: 0
        created_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"

    ApiResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Operation completed successfully"
        data:
          type: object
        metadata:
          type: object
          properties:
            totalCount:
              type: integer
              example: 100
            filteredCount:
              type: integer
              example: 50
            totalPages:
              type: integer
              example: 5
            currentPage:
              type: integer
              example: 1
            limit:
              type: integer
              example: 20
            hasNextPage:
              type: boolean
              example: true
            hasPreviousPage:
              type: boolean
              example: false
        errors:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
                example: "email"
              message:
                type: string
                example: "Email is required"

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "An error occurred"
        errors:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
                example: "email"
              message:
                type: string
                example: "Email is required"

    ServiceProvider:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        user_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174001"
        business_name:
          type: string
          example: "Adventure Tours"
        business_address:
          type: string
          nullable: true
          example: "123 Main St, New York, NY"
        business_phone:
          type: string
          nullable: true
          example: "+1234567890"
        business_email:
          type: string
          format: email
          nullable: true
          example: "info@adventuretours.com"
        website:
          type: string
          nullable: true
          example: "https://www.adventuretours.com"
        description:
          type: string
          nullable: true
          example: "We provide exciting adventure tours around the world."
        verified:
          type: boolean
          example: true
        rating:
          type: number
          format: float
          example: 4.8
        user:
          $ref: "#/components/schemas/User"
        created_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"

    Service:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        provider_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174001"
        name:
          type: string
          example: "Mountain Hiking Tour"
        description:
          type: string
          example: "Experience the thrill of hiking in the mountains with our expert guides."
        price:
          type: number
          format: float
          example: 99.99
        duration:
          type: integer
          example: 180
        location:
          type: string
          nullable: true
          example: "Rocky Mountains"
        category:
          type: string
          example: "Hiking"
        availability:
          type: object
          nullable: true
          example:
            {
              "monday": true,
              "tuesday": true,
              "wednesday": true,
              "thursday": true,
              "friday": true,
            }
        max_participants:
          type: integer
          nullable: true
          example: 10
        images:
          type: array
          items:
            $ref: "#/components/schemas/Image"
        provider:
          $ref: "#/components/schemas/ServiceProvider"
        created_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"

    TravelAgency:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        user_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174001"
        agency_name:
          type: string
          example: "Global Travels"
        agency_address:
          type: string
          nullable: true
          example: "456 Broadway, New York, NY"
        agency_phone:
          type: string
          nullable: true
          example: "+1234567890"
        agency_email:
          type: string
          format: email
          nullable: true
          example: "info@globaltravels.com"
        website:
          type: string
          nullable: true
          example: "https://www.globaltravels.com"
        description:
          type: string
          nullable: true
          example: "We offer comprehensive travel packages worldwide."
        verified:
          type: boolean
          example: true
        rating:
          type: number
          format: float
          example: 4.7
        user:
          $ref: "#/components/schemas/User"
        created_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"

    TravelPackage:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        agency_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174001"
        name:
          type: string
          example: "European Adventure"
        description:
          type: string
          example: "Explore the best of Europe with our comprehensive tour package."
        price:
          type: number
          format: float
          example: 1999.99
        duration:
          type: integer
          example: 14
        inclusions:
          type: array
          items:
            type: string
          example: ["Accommodation", "Breakfast", "Local Guide", "Transportation"]
        exclusions:
          type: array
          items:
            type: string
          example: ["Flights", "Travel Insurance", "Personal Expenses"]
        itinerary:
          type: object
          nullable: true
          example:
            {
              "day1": "Arrival and city tour",
              "day2": "Museum visits",
              "day3": "Free day",
            }
        max_travelers:
          type: integer
          nullable: true
          example: 20
        images:
          type: array
          items:
            $ref: "#/components/schemas/Image"
        destinations:
          type: array
          items:
            $ref: "#/components/schemas/Destination"
        agency:
          $ref: "#/components/schemas/TravelAgency"
        created_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"

    Destination:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        name:
          type: string
          example: "Paris"
        country:
          type: string
          example: "France"
        city:
          type: string
          nullable: true
          example: "Paris"
        description:
          type: string
          example: "The capital of France, known for its art, culture, and history."
        highlights:
          type: array
          items:
            type: string
          example: ["Eiffel Tower", "Louvre Museum", "Notre-Dame Cathedral"]
        best_time_to_visit:
          type: string
          nullable: true
          example: "Spring (April to June) or Fall (September to November)"
        travel_tips:
          type: array
          items:
            type: string
          example:
            [
              "Learn basic French phrases",
              "Use the Metro for transportation",
              "Visit museums on the first Sunday of the month for free entry",
            ]
        latitude:
          type: number
          format: float
          nullable: true
          example: 48.8566
        longitude:
          type: number
          format: float
          nullable: true
          example: 2.3522
        currency:
          type: string
          nullable: true
          example: "EUR"
        language:
          type: string
          nullable: true
          example: "French"
        timezone:
          type: string
          nullable: true
          example: "Europe/Paris"
        safety_index:
          type: number
          format: float
          nullable: true
          minimum: 0
          maximum: 10
          example: 8.5
        cost_index:
          type: number
          format: float
          nullable: true
          minimum: 0
          maximum: 10
          example: 7.2
        featured:
          type: boolean
          example: true
        meta_title:
          type: string
          nullable: true
          example: "Visit Paris - City of Lights | Trippz"
        meta_description:
          type: string
          nullable: true
          example: "Discover the magic of Paris with Trippz. Explore iconic landmarks, world-class cuisine, and rich culture in the heart of France."
        images:
          type: array
          items:
            $ref: "#/components/schemas/Image"
        created_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"

    Notification:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        user_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174001"
        title:
          type: string
          example: "Booking Confirmed"
        message:
          type: string
          example: "Your booking #12345 has been confirmed."
        notification_type:
          type: string
          enum:
            [
              SYSTEM,
              BOOKING,
              PAYMENT,
              PROMOTIONAL,
              REMINDER,
              ALERT,
              NEW_BOOKING,
              TRIP_UPDATES,
              SPECIAL_OFFERS,
            ]
          example: "BOOKING"
        entity_id:
          type: string
          format: uuid
          nullable: true
          example: "123e4567-e89b-12d3-a456-426614174002"
        entity_type:
          type: string
          nullable: true
          example: "BOOKING"
        is_read:
          type: boolean
          example: false
        metadata:
          type: object
          nullable: true
          example:
            { "booking_id": "123e4567-e89b-12d3-a456-426614174002", "amount": 199.99 }
        created_at:
          type: string
          format: date-time
          example: "2023-11-25T14:30:00Z"

    NotificationPreference:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        user_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174001"
        email_enabled:
          type: boolean
          example: true
        sms_enabled:
          type: boolean
          example: true
        push_enabled:
          type: boolean
          example: true
        in_app_enabled:
          type: boolean
          example: true
        system_enabled:
          type: boolean
          example: true
        booking_enabled:
          type: boolean
          example: true
        payment_enabled:
          type: boolean
          example: true
        promotional_enabled:
          type: boolean
          example: false
        reminder_enabled:
          type: boolean
          example: true
        alert_enabled:
          type: boolean
          example: true

    ServiceProviderProfileInput:
      type: object
      required:
        - business_name
      properties:
        business_name:
          type: string
          minLength: 2
          example: "Adventure Tours"
          default: "Adventure Tours"
        business_address:
          type: string
          example: "123 Main St, New York, NY"
          default: "123 Main St, New York, NY"
        business_phone:
          type: string
          example: "+1234567890"
          default: "+1234567890"
        business_email:
          type: string
          format: email
          example: "info@adventuretours.com"
          default: "info@adventuretours.com"
        website:
          type: string
          format: uri
          example: "https://www.adventuretours.com"
          default: "https://www.adventuretours.com"
        description:
          type: string
          example: "We provide exciting adventure tours around the world."
          default: "We provide exciting adventure tours around the world."

    ServiceInput:
      type: object
      required:
        - name
        - description
        - price
        - duration
        - category
      properties:
        name:
          type: string
          minLength: 2
          example: "Mountain Hiking Tour"
          default: "Mountain Hiking Tour"
        description:
          type: string
          minLength: 10
          example: "Experience the thrill of hiking in the mountains with our expert guides."
          default: "Experience the thrill of hiking in the mountains with our expert guides."
        price:
          type: number
          format: float
          minimum: 0
          example: 99.99
          default: 99.99
        duration:
          type: integer
          minimum: 1
          example: 180
          default: 180
        location:
          type: string
          example: "Rocky Mountains"
          default: "Rocky Mountains"
        category:
          type: string
          example: "Hiking"
          default: "Hiking"
        availability:
          type: object
          example:
            {
              "monday": true,
              "tuesday": true,
              "wednesday": true,
              "thursday": true,
              "friday": true,
            }
          default:
            {
              "monday": true,
              "tuesday": true,
              "wednesday": true,
              "thursday": true,
              "friday": true,
            }
        max_participants:
          type: integer
          minimum: 1
          example: 10
          default: 10

    TravelAgencyProfileInput:
      type: object
      required:
        - agency_name
      properties:
        agency_name:
          type: string
          minLength: 2
          example: "Global Travels"
          default: "Global Travels"
        agency_address:
          type: string
          example: "456 Broadway, New York, NY"
          default: "456 Broadway, New York, NY"
        agency_phone:
          type: string
          example: "+1234567890"
          default: "+1234567890"
        agency_email:
          type: string
          format: email
          example: "info@globaltravels.com"
          default: "info@globaltravels.com"
        website:
          type: string
          format: uri
          example: "https://www.globaltravels.com"
          default: "https://www.globaltravels.com"
        description:
          type: string
          example: "We offer comprehensive travel packages worldwide."
          default: "We offer comprehensive travel packages worldwide."

    TravelPackageInput:
      type: object
      required:
        - name
        - description
        - price
        - duration
        - destination_ids
        - inclusions
        - exclusions
      properties:
        name:
          type: string
          minLength: 2
          example: "European Adventure"
          default: "European Adventure"
        description:
          type: string
          minLength: 10
          example: "Explore the best of Europe with our comprehensive tour package."
          default: "Explore the best of Europe with our comprehensive tour package."
        price:
          type: number
          format: float
          minimum: 0
          example: 1999.99
          default: 1999.99
        duration:
          type: integer
          minimum: 1
          example: 14
          default: 14
        destination_ids:
          type: array
          items:
            type: string
            format: uuid
          example:
            [
              "123e4567-e89b-12d3-a456-426614174000",
              "123e4567-e89b-12d3-a456-426614174001",
            ]
          default:
            [
              "123e4567-e89b-12d3-a456-426614174000",
              "123e4567-e89b-12d3-a456-426614174001",
            ]
        inclusions:
          type: array
          items:
            type: string
          example: ["Accommodation", "Breakfast", "Local Guide", "Transportation"]
          default: ["Accommodation", "Breakfast", "Local Guide", "Transportation"]
        exclusions:
          type: array
          items:
            type: string
          example: ["Flights", "Travel Insurance", "Personal Expenses"]
          default: ["Flights", "Travel Insurance", "Personal Expenses"]
        itinerary:
          type: object
          example:
            {
              "day1": "Arrival and city tour",
              "day2": "Museum visits",
              "day3": "Free day",
            }
          default:
            {
              "day1": "Arrival and city tour",
              "day2": "Museum visits",
              "day3": "Free day",
            }
        max_travelers:
          type: integer
          minimum: 1
          example: 20

    DestinationInput:
      type: object
      required:
        - name
        - country
        - description
        - highlights
        - travel_tips
      properties:
        name:
          type: string
          minLength: 2
          example: "Paris"
          default: "Paris"
        country:
          type: string
          minLength: 2
          example: "France"
          default: "France"
        city:
          type: string
          example: "Paris"
          default: "Paris"
        description:
          type: string
          minLength: 10
          example: "The capital of France, known for its art, culture, and history."
          default: "The capital of France, known for its art, culture, and history."
        highlights:
          type: array
          items:
            type: string
          example: ["Eiffel Tower", "Louvre Museum", "Notre-Dame Cathedral"]
          default: ["Eiffel Tower", "Louvre Museum", "Notre-Dame Cathedral"]
        best_time_to_visit:
          type: string
          example: "Spring (April to June) or Fall (September to November)"
          default: "Spring (April to June) or Fall (September to November)"
        travel_tips:
          type: array
          items:
            type: string
          example:
            [
              "Learn basic French phrases",
              "Use the Metro for transportation",
              "Visit museums on the first Sunday of the month for free entry",
            ]
          default:
            [
              "Learn basic French phrases",
              "Use the Metro for transportation",
              "Visit museums on the first Sunday of the month for free entry",
            ]
        latitude:
          type: number
          format: float
          example: 48.8566
          default: 48.8566
        longitude:
          type: number
          format: float
          example: 2.3522
          default: 2.3522
        currency:
          type: string
          example: "EUR"
          default: "EUR"
        language:
          type: string
          example: "French"
          default: "French"
        timezone:
          type: string
          example: "Europe/Paris"
          default: "Europe/Paris"
        safety_index:
          type: number
          format: float
          minimum: 0
          maximum: 10
          example: 8.5
          default: 8.5
        cost_index:
          type: number
          format: float
          minimum: 0
          maximum: 10
          example: 7.2
          default: 7.2
        featured:
          type: boolean
          example: true
          default: true
        meta_title:
          type: string
          maxLength: 60
          example: "Visit Paris - City of Lights | Trippz"
          default: "Visit Paris - City of Lights | Trippz"
        meta_description:
          type: string
          maxLength: 160
          example: "Discover the magic of Paris with Trippz. Explore iconic landmarks, world-class cuisine, and rich culture in the heart of France."
          default: "Discover the magic of Paris with Trippz. Explore iconic landmarks, world-class cuisine, and rich culture in the heart of France."

    SetFeaturedImageInput:
      type: object
      required:
        - imageId
      properties:
        imageId:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
          default: "123e4567-e89b-12d3-a456-426614174000"

    CreateBookingInput:
      type: object
      required:
        - booking_type
        - start_date
        - end_date
      properties:
        booking_type:
          type: string
          enum: [FLIGHT, HOTEL, TRIP]
          example: "HOTEL"
          default: "HOTEL"
        start_date:
          type: string
          format: date
          example: "2023-12-01"
          default: "2023-12-01"
        end_date:
          type: string
          format: date
          example: "2023-12-05"
          default: "2023-12-05"
        flight_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
          default: "123e4567-e89b-12d3-a456-426614174000"
        hotel_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174001"
          default: "123e4567-e89b-12d3-a456-426614174001"
        trip_id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174002"
          default: "123e4567-e89b-12d3-a456-426614174002"

    UpdateBookingInput:
      type: object
      properties:
        start_date:
          type: string
          format: date
          example: "2023-12-02"
          default: "2023-12-02"
        end_date:
          type: string
          format: date
          example: "2023-12-06"
          default: "2023-12-06"
        status:
          type: string
          enum: [PENDING, CONFIRMED, CANCELED, COMPLETED]
          example: "CONFIRMED"
          default: "CONFIRMED"

    NotificationPreferencesInput:
      type: object
      properties:
        email_enabled:
          type: boolean
          example: true
          default: true
        sms_enabled:
          type: boolean
          example: true
          default: true
        push_enabled:
          type: boolean
          example: true
          default: true
        in_app_enabled:
          type: boolean
          example: true
          default: true
        system_enabled:
          type: boolean
          example: true
          default: true
        booking_enabled:
          type: boolean
          example: true
          default: true
        payment_enabled:
          type: boolean
          example: true
          default: true
        promotional_enabled:
          type: boolean
          example: false
          default: false
        reminder_enabled:
          type: boolean
          example: true
          default: true
        alert_enabled:
          type: boolean
          example: true
          default: true

    BulkNotificationInput:
      type: object
      required:
        - userIds
        - title
        - message
        - type
      properties:
        userIds:
          type: array
          items:
            type: string
            format: uuid
          example:
            [
              "123e4567-e89b-12d3-a456-426614174000",
              "123e4567-e89b-12d3-a456-426614174001",
            ]
          default:
            [
              "123e4567-e89b-12d3-a456-426614174000",
              "123e4567-e89b-12d3-a456-426614174001",
            ]
        title:
          type: string
          example: "Special Offer"
          default: "Special Offer"
        message:
          type: string
          example: "Book now and get 20% off on your next trip!"
          default: "Book now and get 20% off on your next trip!"
        type:
          type: string
          enum:
            [
              SYSTEM,
              BOOKING,
              PAYMENT,
              PROMOTIONAL,
              REMINDER,
              ALERT,
              NEW_BOOKING,
              TRIP_UPDATES,
              SPECIAL_OFFERS,
            ]
          example: "PROMOTIONAL"
          default: "PROMOTIONAL"
        channels:
          type: array
          items:
            type: string
            enum: [EMAIL, SMS, PUSH, IN_APP]
          example: ["EMAIL", "PUSH"]
          default: ["EMAIL", "PUSH"]
        entityId:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174002"
          default: "123e4567-e89b-12d3-a456-426614174002"
        entityType:
          type: string
          example: "PROMOTION"
          default: "PROMOTION"
        metadata:
          type: object
          example: { "discount": "20%", "valid_until": "2023-12-31" }
          default: { "discount": "20%", "valid_until": "2023-12-31" }

    SystemSettings:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        maintenance_mode:
          type: boolean
          example: false
          default: false
        booking_fee_percentage:
          type: number
          format: float
          example: 5.0
          default: 5.0
        default_currency:
          type: string
          example: "USD"
          default: "USD"
        support_email:
          type: string
          format: email
          example: "support@trippz.com"
          default: "support@trippz.com"
        support_phone:
          type: string
          example: "+1234567890"
          default: "+1234567890"
        terms_url:
          type: string
          format: url
          example: "https://trippz.com/terms"
          default: "https://trippz.com/terms"
        privacy_url:
          type: string
          format: url
          example: "https://trippz.com/privacy"
          default: "https://trippz.com/privacy"
        created_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2023-01-01T00:00:00Z"

    DashboardStats:
      type: object
      properties:
        users:
          type: object
          properties:
            total:
              type: integer
              example: 1000
            serviceProviders:
              type: integer
              example: 50
            travelAgencies:
              type: integer
              example: 30
        content:
          type: object
          properties:
            destinations:
              type: integer
              example: 100
            packages:
              type: integer
              example: 200
            services:
              type: integer
              example: 300
        orders:
          type: object
          properties:
            serviceOrders:
              type: integer
              example: 500
            packageOrders:
              type: integer
              example: 300
            bookings:
              type: integer
              example: 800
            total:
              type: integer
              example: 1600
        revenue:
          type: object
          properties:
            total:
              type: number
              format: float
              example: 250000.00

    Analytics:
      type: object
      properties:
        userRegistrations:
          type: array
          items:
            type: object
            properties:
              period:
                type: string
                example: "2023-01"
              count:
                type: integer
                example: 120
        bookings:
          type: array
          items:
            type: object
            properties:
              period:
                type: string
                example: "2023-01"
              count:
                type: integer
                example: 85
              total_value:
                type: number
                format: float
                example: 42500.00
        revenue:
          type: array
          items:
            type: object
            properties:
              period:
                type: string
                example: "2023-01"
              revenue:
                type: number
                format: float
                example: 38250.00
        orders:
          type: object
          properties:
            serviceOrdersByStatus:
              type: array
              items:
                type: object
                properties:
                  status:
                    type: string
                    example: "COMPLETED"
                  _count:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 250
            packageOrdersByStatus:
              type: array
              items:
                type: object
                properties:
                  status:
                    type: string
                    example: "COMPLETED"
                  _count:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 150
            bookingsByStatus:
              type: array
              items:
                type: object
                properties:
                  status:
                    type: string
                    example: "CONFIRMED"
                  _count:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 400

    Attraction:
      type: object
      properties:
        name:
          type: string
          example: "Eiffel Tower"
        type:
          type: string
          example: "Monument"
        rating:
          type: number
          format: float
          example: 4.7
        description:
          type: string
          example: "Iconic iron tower offering city views."
        address:
          type: string
          example: "Champ de Mars, 5 Avenue Anatole France"
        image_url:
          type: string
          example: "https://example.com/eiffel.jpg"
        website:
          type: string
          example: "https://www.toureiffel.paris"

paths:
  /auth/register:
    post:
      summary: Register a new user
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterInput"
      responses:
        "201":
          description: User registered successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /auth/login:
    post:
      summary: User login
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginInput"
      responses:
        "200":
          description: Login successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /auth/forgot-password:
    post:
      summary: Request password reset
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ForgotPasswordInput"
      responses:
        "200":
          description: Password reset email sent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /auth/reset-password:
    post:
      summary: Reset password
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResetPasswordInput"
      responses:
        "200":
          description: Password reset successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Invalid or expired token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /auth/verify-email:
    post:
      summary: Verify email
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VerifyEmailInput"
      responses:
        "200":
          description: Email verified successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Invalid or expired token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /auth/verify-phone:
    post:
      summary: Verify phone number
      tags:
        - Authentication
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VerifyPhoneInput"
      responses:
        "200":
          description: Phone verified successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Invalid or expired code
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /auth/logout:
    post:
      summary: Logout current session
      description: Logs out the current user session by invalidating the provided refresh token and clearing authentication cookies. Requires a valid refresh token.
      tags:
        - Authentication
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LogoutInput"
      responses:
        "200":
          description: Successfully logged out the current session
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
              example:
                success: true
                message: Logged out successfully
        "400":
          description: Invalid or missing refresh token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                message: Refresh token is required
        "401":
          description: Unauthorized - Invalid or expired token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                message: Invalid refresh token
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                message: Failed to logout

  /auth/logout-other-devices:
    post:
      summary: Logout from other devices
      description: Logs out the user from all sessions except the current one by invalidating all other refresh tokens. Requires a valid refresh token.
      tags:
        - Authentication
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LogoutInput"
      responses:
        "200":
          description: Successfully logged out from other devices
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
              example:
                success: true
                message: Logged out from other devices successfully
        "400":
          description: Invalid or missing refresh token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                message: Refresh token is required
        "401":
          description: Unauthorized - Invalid or expired token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                message: Invalid refresh token
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                message: Failed to logout from other devices

  /auth/logout-all-devices:
    post:
      summary: Logout from all devices
      description: Logs out the user from all sessions, including the current one, by invalidating all refresh tokens and clearing authentication cookies. Requires a valid refresh token.
      tags:
        - Authentication
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LogoutInput"
      responses:
        "200":
          description: Successfully logged out from all devices
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
              example:
                success: true
                message: Logged out from all devices successfully
        "400":
          description: Invalid or missing refresh token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                message: Refresh token is required
        "401":
          description: Unauthorized - Invalid or expired token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                message: Invalid refresh token
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                message: Failed to logout from all devices

  /auth/refresh-token:
    post:
      summary: Refresh access token
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RefreshTokenInput"
      responses:
        "200":
          description: Tokens refreshed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Invalid refresh token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /auth/google:
    get:
      summary: Initiate Google OAuth flow
      tags:
        - Authentication
      responses:
        "302":
          description: Redirect to Google authentication

  /auth/google/callback:
    get:
      summary: Google OAuth callback
      tags:
        - Authentication
      responses:
        "302":
          description: Redirect to frontend with tokens

  /auth/facebook:
    get:
      summary: Initiate Facebook OAuth flow
      tags:
        - Authentication
      responses:
        "302":
          description: Redirect to Facebook authentication

  /auth/facebook/callback:
    get:
      summary: Facebook OAuth callback
      tags:
        - Authentication
      responses:
        "302":
          description: Redirect to frontend with tokens

  /auth/apple:
    get:
      summary: Initiate Apple OAuth flow
      tags:
        - Authentication
      responses:
        "302":
          description: Redirect to Apple authentication

  /auth/apple/callback:
    post:
      summary: Apple OAuth callback
      tags:
        - Authentication
      responses:
        "302":
          description: Redirect to frontend with tokens

  /users/profile:
    get:
      summary: Get user profile
      tags:
        - Users
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      responses:
        "200":
          description: User profile retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    put:
      summary: Update user profile
      tags:
        - Users
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  minLength: 2
                  example: "Asikur"
                last_name:
                  type: string
                  minLength: 2
                  example: "Rahman"
                date_of_birth:
                  type: string
                  format: date
                  example: "1990-01-01"
                address:
                  type: string
                  example: "123 Main St, Dhaka, Bangladesh"
                bio:
                  type: string
                  example: "Travel enthusiast and adventure seeker."
                theme:
                  type: string
                  example: "dark"
                language:
                  type: string
                  example: "en"
      responses:
        "200":
          description: Profile updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /users/password:
    put:
      summary: Update password
      tags:
        - Users
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - current_password
                - new_password
                - confirm_password
              properties:
                current_password:
                  type: string
                  example: "12345678"
                new_password:
                  type: string
                  minLength: 8
                  example: "newpassword123"
                confirm_password:
                  type: string
                  example: "newpassword123"
      responses:
        "200":
          description: Password updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error or incorrect current password
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /users/profile-picture:
    post:
      summary: Upload profile picture
      tags:
        - Users
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Profile picture uploaded successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Invalid file
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /users/addresses:
    post:
      summary: Add address
      tags:
        - Users
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - address
                - city
                - country
                - postal_code
              properties:
                address:
                  type: string
                  example: "123 Main St"
                city:
                  type: string
                  example: "Dhaka"
                country:
                  type: string
                  example: "Bangladesh"
                postal_code:
                  type: string
                  example: "1000"
      responses:
        "201":
          description: Address added successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    get:
      summary: Get user addresses
      tags:
        - Users
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      responses:
        "200":
          description: Addresses retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /users/addresses/{id}:
    delete:
      summary: Delete address
      tags:
        - Users
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Address deleted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Address not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /destinations:
    get:
      summary: Get all destinations with filtering and pagination
      tags:
        - Destinations
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
        - name: search
          in: query
          schema:
            type: string
          example: "paris"
        - name: country
          in: query
          schema:
            type: string
          example: "france"
        - name: featured
          in: query
          schema:
            type: boolean
          example: true
        - name: sortBy
          in: query
          schema:
            type: string
            default: "name"
          example: "name"
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: "asc"
          example: "asc"
      responses:
        "200":
          description: Destinations retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    post:
      summary: Create a new destination
      tags:
        - Destinations
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Paris"
                country:
                  type: string
                  example: "France"
                city:
                  type: string
                  example: "Paris"
                description:
                  type: string
                  example: "The capital of France, known for its art, culture, and history."
                highlights:
                  type: array
                  items:
                    type: string
                  example: ["Eiffel Tower", "Louvre Museum", "Notre-Dame Cathedral"]
                best_time_to_visit:
                  type: string
                  example: "Spring (April to June) or Fall (September to November)"
                travel_tips:
                  type: array
                  items:
                    type: string
                  example:
                    [
                      "Learn basic French phrases",
                      "Use the Metro for transportation",
                      "Visit museums on the first Sunday of the month for free entry",
                    ]
                latitude:
                  type: number
                  format: float
                  example: 48.8566
                longitude:
                  type: number
                  format: float
                  example: 2.3522
                currency:
                  type: string
                  example: "EUR"
                language:
                  type: string
                  example: "French"
                timezone:
                  type: string
                  example: "Europe/Paris"
                safety_index:
                  type: number
                  format: float
                  example: 8.5
                cost_index:
                  type: number
                  format: float
                  example: 7.2
                featured:
                  type: boolean
                  example: true
                meta_title:
                  type: string
                  example: "Visit Paris - City of Lights | Trippz"
                meta_description:
                  type: string
                  example: "Discover the magic of Paris with Trippz. Explore iconic landmarks, world-class cuisine, and rich culture in the heart of France."
                files:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        "201":
          description: Destination created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /destinations/trending:
    get:
      summary: Get trending destinations
      tags:
        - Destinations
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 5
          example: 5
      responses:
        "200":
          description: Trending destinations retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /destinations/nearby:
    get:
      summary: Get nearby destinations based on coordinates
      tags:
        - Destinations
      parameters:
        - name: latitude
          in: query
          required: true
          schema:
            type: number
            format: float
          example: 48.8566
        - name: longitude
          in: query
          required: true
          schema:
            type: number
            format: float
          example: 2.3522
        - name: radius
          in: query
          schema:
            type: integer
            default: 100
          example: 100
        - name: limit
          in: query
          schema:
            type: integer
            default: 5
          example: 5
      responses:
        "200":
          description: Nearby destinations retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /destinations/{id}:
    get:
      summary: Get destination by ID
      tags:
        - Destinations
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Destination retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Destination not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    put:
      summary: Update destination
      tags:
        - Destinations
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Paris"
                country:
                  type: string
                  example: "France"
                city:
                  type: string
                  example: "Paris"
                description:
                  type: string
                  example: "The capital of France, known for its art, culture, and history."
                highlights:
                  type: array
                  items:
                    type: string
                  example: ["Eiffel Tower", "Louvre Museum", "Notre-Dame Cathedral"]
                best_time_to_visit:
                  type: string
                  example: "Spring (April to June) or Fall (September to November)"
                travel_tips:
                  type: array
                  items:
                    type: string
                  example:
                    [
                      "Learn basic French phrases",
                      "Use the Metro for transportation",
                      "Visit museums on the first Sunday of the month for free entry",
                    ]
                latitude:
                  type: number
                  format: float
                  example: 48.8566
                longitude:
                  type: number
                  format: float
                  example: 2.3522
                currency:
                  type: string
                  example: "EUR"
                language:
                  type: string
                  example: "French"
                timezone:
                  type: string
                  example: "Europe/Paris"
                safety_index:
                  type: number
                  format: float
                  example: 8.5
                cost_index:
                  type: number
                  format: float
                  example: 7.2
                featured:
                  type: boolean
                  example: true
                meta_title:
                  type: string
                  example: "Visit Paris - City of Lights | Trippz"
                meta_description:
                  type: string
                  example: "Discover the magic of Paris with Trippz. Explore iconic landmarks, world-class cuisine, and rich culture in the heart of France."
                files:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        "200":
          description: Destination updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Destination not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    delete:
      summary: Delete destination
      tags:
        - Destinations
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Destination deleted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Cannot delete destination that is used in travel packages
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Destination not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /destinations/{id}/featured-image:
    put:
      summary: Set featured image for destination
      tags:
        - Destinations
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetFeaturedImageInput"
      responses:
        "200":
          description: Featured image updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Destination or image not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /destinations/{id}/weather:
    get:
      summary: Get weather information for a destination
      tags:
        - Destinations
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Weather information retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Destination coordinates not available
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Destination not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /destinations/{id}/attractions:
    get:
      summary: Get attractions for a destination
      tags:
        - Destinations
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
          example: 10
      responses:
        "200":
          description: Attractions retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Destination not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /flights:
    get:
      summary: Get all flights with filtering and pagination
      tags:
        - Flights
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
        - name: from
          in: query
          schema:
            type: string
          example: "LHR"
        - name: to
          in: query
          schema:
            type: string
          example: "JFK"
        - name: departure_date
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-01"
        - name: return_date
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-15"
        - name: airline
          in: query
          schema:
            type: string
          example: "British Airways"
        - name: minPrice
          in: query
          schema:
            type: number
          example: 300
        - name: maxPrice
          in: query
          schema:
            type: number
          example: 1000
        - name: seat_class
          in: query
          schema:
            type: string
          example: "Economy"
        - name: direct_flights_only
          in: query
          schema:
            type: boolean
          example: true
        - name: has_wifi
          in: query
          schema:
            type: boolean
          example: true
        - name: has_entertainment
          in: query
          schema:
            type: boolean
          example: true
        - name: has_power_outlets
          in: query
          schema:
            type: boolean
          example: true
        - name: meal_service
          in: query
          schema:
            type: boolean
          example: true
        - name: min_baggage_allowance
          in: query
          schema:
            type: integer
          example: 2
        - name: sortBy
          in: query
          schema:
            type: string
            default: "departure_time"
          example: "departure_time"
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: "asc"
          example: "asc"
      responses:
        "200":
          description: Flights retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    post:
      summary: Create a new flight
      tags:
        - Flights
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateFlightInput"
      responses:
        "201":
          description: Flight created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden - Not authorized to create flights
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /flights/search:
    get:
      summary: Search flights with advanced filtering
      tags:
        - Flights
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
        - name: from
          in: query
          schema:
            type: string
          example: "LHR"
        - name: to
          in: query
          schema:
            type: string
          example: "JFK"
        - name: departure_date
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-01"
        - name: return_date
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-15"
        - name: passengers
          in: query
          schema:
            type: integer
          example: 2
        - name: seat_class
          in: query
          schema:
            type: string
          example: "Economy"
        - name: airline
          in: query
          schema:
            type: string
          example: "British Airways"
        - name: minPrice
          in: query
          schema:
            type: number
          example: 300
        - name: maxPrice
          in: query
          schema:
            type: number
          example: 1000
        - name: direct_flights_only
          in: query
          schema:
            type: boolean
          example: true
        - name: has_wifi
          in: query
          schema:
            type: boolean
          example: true
        - name: has_entertainment
          in: query
          schema:
            type: boolean
          example: true
        - name: has_power_outlets
          in: query
          schema:
            type: boolean
          example: true
        - name: meal_service
          in: query
          schema:
            type: boolean
          example: true
        - name: min_baggage_allowance
          in: query
          schema:
            type: integer
          example: 2
        - name: sortBy
          in: query
          schema:
            type: string
            default: "price"
          example: "price"
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: "asc"
          example: "asc"
      responses:
        "200":
          description: Flights search results retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /flights/custom-search:
    get:
      summary: Custom flight search with advanced parameters
      tags:
        - Flights
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
        - name: layover_max_hours
          in: query
          schema:
            type: integer
          example: 3
        - name: preferred_airlines
          in: query
          schema:
            type: array
            items:
              type: string
          explode: true
          example: ["British Airways", "Lufthansa"]
        - name: exclude_airlines
          in: query
          schema:
            type: array
            items:
              type: string
          explode: true
          example: ["Budget Air"]
        - name: departure_time_start
          in: query
          schema:
            type: string
            format: date-time
          example: "2023-12-01T06:00:00Z"
        - name: departure_time_end
          in: query
          schema:
            type: string
            format: date-time
          example: "2023-12-01T12:00:00Z"
        - name: arrival_time_start
          in: query
          schema:
            type: string
            format: date-time
          example: "2023-12-01T14:00:00Z"
        - name: arrival_time_end
          in: query
          schema:
            type: string
            format: date-time
          example: "2023-12-01T20:00:00Z"
        - name: price_range
          in: query
          schema:
            type: string
          example: "300-800"
        - name: duration_max_minutes
          in: query
          schema:
            type: integer
          example: 480
        - name: sortBy
          in: query
          schema:
            type: string
            default: "departure_time"
          example: "departure_time"
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: "asc"
          example: "asc"
      responses:
        "200":
          description: Custom flight search results retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /flights/{id}:
    get:
      summary: Get flight by ID
      tags:
        - Flights
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Flight retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Flight not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    patch:
      summary: Update flight
      tags:
        - Flights
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateFlightInput"
      responses:
        "200":
          description: Flight updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden - Not authorized to update flights
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Flight not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      summary: Delete flight
      tags:
        - Flights
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Flight deleted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Cannot delete flight with active bookings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden - Not authorized to delete flights
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Flight not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /flights/{id}/availability:
    get:
      summary: Check flight availability
      tags:
        - Flights
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        - name: date
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-01"
        - name: passengers
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 2
      responses:
        "200":
          description: Flight availability retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Flight not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /hotels:
    get:
      summary: Get all hotels with filtering and pagination
      tags:
        - Hotels
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
        - name: location
          in: query
          schema:
            type: string
          example: "New York"
        - name: city
          in: query
          schema:
            type: string
          example: "New York"
        - name: country
          in: query
          schema:
            type: string
          example: "USA"
        - name: check_in
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-01"
        - name: check_out
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-05"
        - name: guests
          in: query
          schema:
            type: integer
          example: 2
        - name: rooms
          in: query
          schema:
            type: integer
          example: 1
        - name: minPrice
          in: query
          schema:
            type: number
          example: 100
        - name: maxPrice
          in: query
          schema:
            type: number
          example: 500
        - name: rating
          in: query
          schema:
            type: number
          example: 4
        - name: amenities
          in: query
          schema:
            type: array
            items:
              type: string
          explode: true
          example: ["WiFi", "Pool", "Gym"]
        - name: has_free_cancellation
          in: query
          schema:
            type: boolean
          example: true
        - name: has_breakfast_included
          in: query
          schema:
            type: boolean
          example: true
        - name: has_parking
          in: query
          schema:
            type: boolean
          example: true
        - name: has_pool
          in: query
          schema:
            type: boolean
          example: true
        - name: has_gym
          in: query
          schema:
            type: boolean
          example: true
        - name: has_restaurant
          in: query
          schema:
            type: boolean
          example: true
        - name: has_room_service
          in: query
          schema:
            type: boolean
          example: true
        - name: has_spa
          in: query
          schema:
            type: boolean
          example: true
        - name: has_wifi
          in: query
          schema:
            type: boolean
          example: true
        - name: has_air_conditioning
          in: query
          schema:
            type: boolean
          example: true
        - name: is_pet_friendly
          in: query
          schema:
            type: boolean
          example: true
        - name: is_family_friendly
          in: query
          schema:
            type: boolean
          example: true
        - name: distance_from_center
          in: query
          schema:
            type: number
          example: 2
        - name: sortBy
          in: query
          schema:
            type: string
            default: "created_at"
          example: "price_per_night"
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: "desc"
          example: "asc"
      responses:
        "200":
          description: Hotels retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    post:
      summary: Create a new hotel
      tags:
        - Hotels
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateHotelInput"
      responses:
        "201":
          description: Hotel created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden - Not authorized to create hotels
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /hotels/search:
    get:
      summary: Search hotels with advanced filtering
      tags:
        - Hotels
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
        - name: location
          in: query
          schema:
            type: string
          example: "New York"
        - name: city
          in: query
          schema:
            type: string
          example: "New York"
        - name: country
          in: query
          schema:
            type: string
          example: "USA"
        - name: check_in
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-01"
        - name: check_out
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-05"
        - name: guests
          in: query
          schema:
            type: integer
          example: 2
        - name: rooms
          in: query
          schema:
            type: integer
          example: 1
        - name: minPrice
          in: query
          schema:
            type: number
          example: 100
        - name: maxPrice
          in: query
          schema:
            type: number
          example: 500
        - name: rating
          in: query
          schema:
            type: number
          example: 4
        - name: amenities
          in: query
          schema:
            type: array
            items:
              type: string
          explode: true
          example: ["WiFi", "Pool", "Gym"]
        - name: has_free_cancellation
          in: query
          schema:
            type: boolean
          example: true
        - name: has_breakfast_included
          in: query
          schema:
            type: boolean
          example: true
        - name: has_parking
          in: query
          schema:
            type: boolean
          example: true
        - name: has_pool
          in: query
          schema:
            type: boolean
          example: true
        - name: has_gym
          in: query
          schema:
            type: boolean
          example: true
        - name: has_restaurant
          in: query
          schema:
            type: boolean
          example: true
        - name: has_room_service
          in: query
          schema:
            type: boolean
          example: true
        - name: has_spa
          in: query
          schema:
            type: boolean
          example: true
        - name: has_wifi
          in: query
          schema:
            type: boolean
          example: true
        - name: has_air_conditioning
          in: query
          schema:
            type: boolean
          example: true
        - name: is_pet_friendly
          in: query
          schema:
            type: boolean
          example: true
        - name: is_family_friendly
          in: query
          schema:
            type: boolean
          example: true
        - name: distance_from_center
          in: query
          schema:
            type: number
          example: 2
        - name: sortBy
          in: query
          schema:
            type: string
            default: "price_per_night"
          example: "price_per_night"
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: "asc"
          example: "asc"
      responses:
        "200":
          description: Hotels search results retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /hotels/custom-search:
    get:
      summary: Custom hotel search with advanced parameters
      tags:
        - Hotels
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
        - name: nearby_attractions
          in: query
          schema:
            type: string
          example: "Times Square"
        - name: nearby_landmarks
          in: query
          schema:
            type: string
          example: "Central Park"
        - name: nearby_restaurants
          in: query
          schema:
            type: boolean
          example: true
        - name: nearby_shopping
          in: query
          schema:
            type: boolean
          example: true
        - name: nearby_public_transport
          in: query
          schema:
            type: boolean
          example: true
        - name: distance_radius
          in: query
          schema:
            type: number
          example: 5
        - name: property_type
          in: query
          schema:
            type: string
          example: "Resort"
        - name: star_rating
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 5
          example: 5
        - name: guest_rating_min
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 5
          example: 4.5
        - name: room_types
          in: query
          schema:
            type: array
            items:
              type: string
          explode: true
          example: ["Suite", "Deluxe"]
        - name: sortBy
          in: query
          schema:
            type: string
            default: "rating"
          example: "rating"
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: "desc"
          example: "desc"
      responses:
        "200":
          description: Custom hotel search results retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /hotels/{id}:
    get:
      summary: Get hotel by ID
      tags:
        - Hotels
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Hotel retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Hotel not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    patch:
      summary: Update hotel
      tags:
        - Hotels
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateHotelInput"
      responses:
        "200":
          description: Hotel updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden - Not authorized to update hotels
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Hotel not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      summary: Delete hotel
      tags:
        - Hotels
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Hotel deleted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Cannot delete hotel with active bookings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden - Not authorized to delete hotels
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Hotel not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /hotels/{id}/availability:
    get:
      summary: Check hotel availability
      tags:
        - Hotels
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        - name: check_in
          in: query
          required: true
          schema:
            type: string
            format: date
          example: "2023-12-01"
        - name: check_out
          in: query
          required: true
          schema:
            type: string
            format: date
          example: "2023-12-05"
        - name: guests
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 2
        - name: rooms
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 1
      responses:
        "200":
          description: Hotel availability retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Hotel not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /trips:
    get:
      summary: Get all trips with filtering and pagination
      tags:
        - Trips
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
        - name: trip_type
          in: query
          schema:
            type: string
            enum: [ADVENTURE, MEDICAL, BUSINESS, LEISURE]
          example: "ADVENTURE"
        - name: destination
          in: query
          schema:
            type: string
          example: "Paris"
        - name: start_date
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-01"
        - name: end_date
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-31"
        - name: minPrice
          in: query
          schema:
            type: number
          example: 1000
        - name: maxPrice
          in: query
          schema:
            type: number
          example: 3000
        - name: duration_min
          in: query
          schema:
            type: integer
          example: 7
        - name: duration_max
          in: query
          schema:
            type: integer
          example: 14
        - name: min_rating
          in: query
          schema:
            type: number
          example: 4
        - name: max_participants
          in: query
          schema:
            type: integer
          example: 20
        - name: has_availability
          in: query
          schema:
            type: boolean
          example: true
        - name: includes_flight
          in: query
          schema:
            type: boolean
          example: false
        - name: includes_hotel
          in: query
          schema:
            type: boolean
          example: true
        - name: includes_activities
          in: query
          schema:
            type: boolean
          example: true
        - name: includes_meals
          in: query
          schema:
            type: boolean
          example: true
        - name: is_guided
          in: query
          schema:
            type: boolean
          example: true
        - name: is_family_friendly
          in: query
          schema:
            type: boolean
          example: true
        - name: is_accessible
          in: query
          schema:
            type: boolean
          example: false
        - name: has_free_cancellation
          in: query
          schema:
            type: boolean
          example: true
        - name: sortBy
          in: query
          schema:
            type: string
            default: "created_at"
          example: "start_date"
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: "desc"
          example: "asc"
      responses:
        "200":
          description: Trips retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    post:
      summary: Create a new trip
      tags:
        - Trips
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTripInput"
      responses:
        "201":
          description: Trip created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /trips/search:
    get:
      summary: Search trips with advanced filtering
      tags:
        - Trips
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
        - name: trip_type
          in: query
          schema:
            type: string
            enum: [ADVENTURE, MEDICAL, BUSINESS, LEISURE]
          example: "ADVENTURE"
        - name: destination
          in: query
          schema:
            type: string
          example: "Paris"
        - name: start_date
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-01"
        - name: end_date
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-31"
        - name: minPrice
          in: query
          schema:
            type: number
          example: 1000
        - name: maxPrice
          in: query
          schema:
            type: number
          example: 3000
        - name: duration_min
          in: query
          schema:
            type: integer
          example: 7
        - name: duration_max
          in: query
          schema:
            type: integer
          example: 14
        - name: min_rating
          in: query
          schema:
            type: number
          example: 4
        - name: max_participants
          in: query
          schema:
            type: integer
          example: 20
        - name: has_availability
          in: query
          schema:
            type: boolean
          example: true
        - name: includes_flight
          in: query
          schema:
            type: boolean
          example: false
        - name: includes_hotel
          in: query
          schema:
            type: boolean
          example: true
        - name: includes_activities
          in: query
          schema:
            type: boolean
          example: true
        - name: includes_meals
          in: query
          schema:
            type: boolean
          example: true
        - name: is_guided
          in: query
          schema:
            type: boolean
          example: true
        - name: is_family_friendly
          in: query
          schema:
            type: boolean
          example: true
        - name: is_accessible
          in: query
          schema:
            type: boolean
          example: false
        - name: has_free_cancellation
          in: query
          schema:
            type: boolean
          example: true
        - name: sortBy
          in: query
          schema:
            type: string
            default: "price"
          example: "price"
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: "asc"
          example: "asc"
      responses:
        "200":
          description: Trips search results retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /trips/custom-search:
    get:
      summary: Custom trip search with advanced parameters
      tags:
        - Trips
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
        - name: destinations
          in: query
          schema:
            type: array
            items:
              type: string
          explode: true
          example: ["Paris", "Rome", "Barcelona"]
        - name: activities
          in: query
          schema:
            type: array
            items:
              type: string
          explode: true
          example: ["Hiking", "Museum Tours", "Wine Tasting"]
        - name: themes
          in: query
          schema:
            type: array
            items:
              type: string
          explode: true
          example: ["Cultural", "Historical", "Culinary"]
        - name: travel_styles
          in: query
          schema:
            type: array
            items:
              type: string
          explode: true
          example: ["Luxury", "Budget", "Family"]
        - name: group_size
          in: query
          schema:
            type: integer
          example: 10
        - name: price_range
          in: query
          schema:
            type: string
          example: "1000-3000"
        - name: duration_range
          in: query
          schema:
            type: string
          example: "7-14"
        - name: departure_months
          in: query
          schema:
            type: array
            items:
              type: string
          explode: true
          example: ["June", "July", "August"]
        - name: difficulty_level
          in: query
          schema:
            type: string
          example: "Moderate"
        - name: sortBy
          in: query
          schema:
            type: string
            default: "price"
          example: "price"
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: "asc"
          example: "asc"
      responses:
        "200":
          description: Custom trip search results retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /trips/{id}:
    get:
      summary: Get trip availability
      tags:
        - Trips
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date
          example: "2023-12-01"
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date
          example: "2023-12-15"
      responses:
        "200":
          description: Trip availability retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Trip not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /notifications:
    get:
      summary: Get user notifications with pagination
      tags:
        - Notifications
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
      responses:
        "200":
          description: Notifications retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /notifications/{id}/read:
    put:
      summary: Mark notification as read
      tags:
        - Notifications
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Notification marked as read
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not the notification owner
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Notification not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /notifications/read-all:
    put:
      summary: Mark all notifications as read
      tags:
        - Notifications
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      responses:
        "200":
          description: All notifications marked as read
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /notifications/{id}:
    delete:
      summary: Delete notification
      tags:
        - Notifications
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Notification deleted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not the notification owner
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Notification not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /notifications/preferences:
    get:
      summary: Get user notification preferences
      tags:
        - Notifications
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      responses:
        "200":
          description: Notification preferences retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    put:
      summary: Update user notification preferences
      tags:
        - Notifications
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationPreferencesInput"
      responses:
        "200":
          description: Notification preferences updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /notifications/bulk:
    post:
      summary: Send bulk notifications (Admin only)
      tags:
        - Notifications
        - Admin
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkNotificationInput"
      responses:
        "200":
          description: Bulk notifications sent successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /bookings:
    post:
      summary: Create a new booking
      tags:
        - Bookings
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateBookingInput"
      responses:
        "201":
          description: Booking created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    get:
      summary: Get user bookings
      tags:
        - Bookings
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
        - name: status
          in: query
          schema:
            type: string
            enum: [PENDING, CONFIRMED, CANCELED, COMPLETED]
          example: "CONFIRMED"
        - name: bookingType
          in: query
          schema:
            type: string
            enum: [FLIGHT, HOTEL, TRIP]
          example: "HOTEL"
        - name: startDate
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-01"
        - name: endDate
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-15"
      responses:
        "200":
          description: Bookings retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /bookings/{id}:
    get:
      summary: Get booking by ID
      tags:
        - Bookings
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Booking retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not the booking owner
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Booking not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    put:
      summary: Update booking
      tags:
        - Bookings
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateBookingInput"
      responses:
        "200":
          description: Booking updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not the booking owner
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Booking not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /bookings/{id}/cancel:
    post:
      summary: Cancel booking
      tags:
        - Bookings
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Booking canceled successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Booking cannot be canceled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not the booking owner
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Booking not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /payments:
    post:
      summary: Process payment
      tags:
        - Payments
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - booking_id
                - payment_method
              properties:
                booking_id:
                  type: string
                  format: uuid
                  example: "123e4567-e89b-12d3-a456-426614174000"
                payment_method:
                  type: string
                  enum: [CREDIT_CARD, PAYPAL, GOOGLE_PAY, APPLE_PAY]
                  example: "CREDIT_CARD"
                card_number:
                  type: string
                  example: "4242424242424242"
                card_expiry:
                  type: string
                  example: "12/25"
                card_cvv:
                  type: string
                  example: "123"
                billing_address:
                  type: string
                  example: "123 Main St, New York, NY"
      responses:
        "200":
          description: Payment processed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error or payment processing error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not the booking owner
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Booking not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    get:
      summary: Get user payments
      tags:
        - Payments
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
        - name: status
          in: query
          schema:
            type: string
            enum: [PENDING, SUCCESS, FAILED, REFUNDED]
          example: "SUCCESS"
      responses:
        "200":
          description: Payments retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /payments/{id}:
    get:
      summary: Get payment by ID
      tags:
        - Payments
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Payment retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not the payment owner
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /payments/{id}/refund:
    post:
      summary: Refund payment
      tags:
        - Payments
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  example: "Customer requested cancellation"

                amount:
                  type: number
                  format: float
                  example: 199.99
      responses:
        "200":
          description: Payment refunded successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Payment cannot be refunded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not the payment owner
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /reviews:
    post:
      summary: Create a review
      tags:
        - Reviews
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - rating
              properties:
                hotel_id:
                  type: string
                  format: uuid
                  example: "123e4567-e89b-12d3-a456-426614174000"
                flight_id:
                  type: string
                  format: uuid
                  example: "123e4567-e89b-12d3-a456-426614174001"
                trip_id:
                  type: string
                  format: uuid
                  example: "123e4567-e89b-12d3-a456-426614174002"
                rating:
                  type: number
                  minimum: 1
                  maximum: 5
                  example: 4.5
                comment:
                  type: string
                  example: "Great experience! Would definitely recommend."
      responses:
        "201":
          description: Review created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    get:
      summary: Get user reviews
      tags:
        - Reviews
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      responses:
        "200":
          description: Reviews retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /reviews/{id}:
    get:
      summary: Get review by ID
      tags:
        - Reviews
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Review retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Review not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    put:
      summary: Update review
      tags:
        - Reviews
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rating:
                  type: number
                  minimum: 1
                  maximum: 5
                  example: 5
                comment:
                  type: string
                  example: "Absolutely fantastic experience! Highly recommended."
      responses:
        "200":
          description: Review updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not the review owner
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Review not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    delete:
      summary: Delete review
      tags:
        - Reviews
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Review deleted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not the review owner
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: Review not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /service-providers/register:
    post:
      summary: Register as service provider
      tags:
        - Service Providers
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ServiceProviderProfileInput"
      responses:
        "201":
          description: Registered as service provider successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /travel-agencies/register:
    post:
      summary: Register as travel agency
      tags:
        - Travel Agencies
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TravelAgencyProfileInput"
      responses:
        "201":
          description: Registered as travel agency successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /health:
    get:
      summary: Health check endpoint
      tags:
        - System
      responses:
        "200":
          description: Server is running
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "ok"
                  message:
                    type: string
                    example: "Server is running"

  /maintenance-status:
    get:
      summary: Get system maintenance status
      tags:
        - System
      responses:
        "200":
          description: Maintenance status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  data:
                    type: object
                    properties:
                      maintenance_mode:
                        type: boolean
                        example: false
                      message:
                        type: string
                        example: "System is operational"

  /admin/settings:
    get:
      summary: Get system settings (Admin only)
      tags:
        - Admin
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      responses:
        "200":
          description: System settings retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    put:
      summary: Update system settings (Admin only)
      tags:
        - Admin
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                maintenance_mode:
                  type: boolean
                  example: false
                booking_fee_percentage:
                  type: number
                  format: float
                  example: 5.0
                default_currency:
                  type: string
                  example: "USD"
                support_email:
                  type: string
                  format: email
                  example: "support@trippz.com"
                support_phone:
                  type: string
                  example: "+1234567890"
                terms_url:
                  type: string
                  format: url
                  example: "https://trippz.com/terms"
                privacy_url:
                  type: string
                  format: url
                  example: "https://trippz.com/privacy"
      responses:
        "200":
          description: System settings updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /admin/stats:
    get:
      summary: Get dashboard statistics (Admin only)
      tags:
        - Admin
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      responses:
        "200":
          description: Statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /admin/analytics:
    get:
      summary: Get detailed analytics (Admin only)
      tags:
        - Admin
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: period
          in: query
          schema:
            type: string
            enum: [daily, weekly, monthly, yearly]
            default: "monthly"
          example: "monthly"
        - name: startDate
          in: query
          schema:
            type: string
            format: date
          example: "2023-01-01"
        - name: endDate
          in: query
          schema:
            type: string
            format: date
          example: "2023-12-31"
      responses:
        "200":
          description: Analytics retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /admin/users:
    get:
      summary: Get all users (Admin only)
      tags:
        - Admin
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          example: 20
        - name: search
          in: query
          schema:
            type: string
          example: "john"
        - name: role
          in: query
          schema:
            type: string
            enum: [USER, SERVICE_PROVIDER, TRAVEL_AGENCY, ADMIN]
          example: "USER"
        - name: sortBy
          in: query
          schema:
            type: string
            default: "created_at"
          example: "created_at"
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: "desc"
          example: "desc"
      responses:
        "200":
          description: Users retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /admin/users/{id}:
    get:
      summary: Get user by ID (Admin only)
      tags:
        - Admin
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: User retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

    delete:
      summary: Delete user (Admin only)
      tags:
        - Admin
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: User deleted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /admin/users/{id}/role:
    put:
      summary: Update user role (Admin only)
      tags:
        - Admin
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - role
              properties:
                role:
                  type: string
                  enum: [USER, SERVICE_PROVIDER, TRAVEL_AGENCY, ADMIN]
                  example: "SERVICE_PROVIDER"
      responses:
        "200":
          description: User role updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /admin/destinations:
    get:
      summary: Get all destinations (Admin only)
      tags:
        - Admin
      security:
        - TrippzHeaderAuth: []
        - CookieAccessToken: []
        - TrippzRefreshTokenHeader: []
        - CookieRefreshToken: []

      responses:
        "200":
          description: Destinations retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: Forbidden - Not an admin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"