openapi: 3.0.0
info:
  title: FreeTube - Video Sharing Platform API
  version: 1.0.0
  description: API documentation for the FreeTube Video Sharing Platform
  contact:
    name: FreeTube Team
    email: contact@freetube.com
servers:
  - url: https://localhost
    description: Local development server

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        email:
          type: string
          format: email
        picture:
          type: string
        created_at:
          type: string
          format: date-time
    
    Channel:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        owner:
          type: integer
        subscribers:
          type: integer
        created_at:
          type: string
          format: date-time
    
    Video:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        description:
          type: string
        file:
          type: string
        thumbnail:
          type: string
        visibility:
          type: string
          enum: [public, private, unlisted]
        channel:
          type: integer
        views:
          type: integer
        likes:
          type: integer
        release_date:
          type: string
          format: date-time
        tags:
          type: array
          items:
            type: string
    
    Comment:
      type: object
      properties:
        id:
          type: integer
        content:
          type: string
        video:
          type: integer
        author:
          type: integer
        created_at:
          type: string
          format: date-time
    
    Playlist:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        owner:
          type: integer
        created_at:
          type: string
          format: date-time
    
    Error:
      type: object
      properties:
        message:
          type: string
        error:
          type: string

paths:
  # USER ENDPOINTS
  /api/users:
    post:
      tags:
        - Users
      summary: Register a new user
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                username:
                  type: string
                email:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 6
                profile:
                  type: string
                  format: binary
              required:
                - username
                - email
                - password
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request - validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: User already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/users/login:
    post:
      tags:
        - Users
      summary: Login user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string
              required:
                - username
                - password
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                  user:
                    $ref: '#/components/schemas/User'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/users/search:
    get:
      tags:
        - Users
      summary: Search users by username
      security:
        - BearerAuth: []
      parameters:
        - name: username
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Users found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/users/{id}:
    get:
      tags:
        - Users
      summary: Get user by ID
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    
    put:
      tags:
        - Users
      summary: Update user
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                email:
                  type: string
                  format: email
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      tags:
        - Users
      summary: Delete user
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/users/username/{username}:
    get:
      tags:
        - Users
      summary: Get user by username
      security:
        - BearerAuth: []
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/users/{id}/channel:
    get:
      tags:
        - Users
      summary: Get user's channel
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Channel found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '404':
          description: Channel not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/users/{id}/history:
    get:
      tags:
        - Users
      summary: Get user's watch history
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: History retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Video'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/users/{id}/subscriptions:
    get:
      tags:
        - Users
      summary: Get user's subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Subscriptions retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Channel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/users/{id}/subscriptions/videos:
    get:
      tags:
        - Users
      summary: Get videos from subscribed channels
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Subscription videos retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Video'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/users/verify-email:
    post:
      tags:
        - Users
      summary: Verify user email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                email:
                  type: string
                  format: email
              required:
                - token
                - email
      responses:
        '200':
          description: Email verified successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          description: Invalid or expired token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # CHANNEL ENDPOINTS
  /api/channels:
    post:
      tags:
        - Channels
      summary: Create a new channel
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                owner:
                  type: integer
              required:
                - name
                - description
                - owner
      responses:
        '201':
          description: Channel created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Channel name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    get:
      tags:
        - Channels
      summary: Get all channels
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Channels retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Channel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/channels/{id}:
    get:
      tags:
        - Channels
      summary: Get channel by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Channel found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '404':
          description: Channel not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      tags:
        - Channels
      summary: Update channel
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: Channel updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Channel not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      tags:
        - Channels
      summary: Delete channel
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Channel deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Channel not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/channels/{id}/subscribe:
    post:
      tags:
        - Channels
      summary: Toggle subscription to channel
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: integer
              required:
                - userId
      responses:
        '200':
          description: Subscription toggled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscribed:
                    type: boolean
                  subscriptions:
                    type: integer
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Channel not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/channels/{id}/stats:
    get:
      tags:
        - Channels
      summary: Get channel statistics
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Channel statistics retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_views:
                    type: integer
                  subscribers:
                    type: integer
                  videos_count:
                    type: integer
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Channel not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # VIDEO ENDPOINTS
  /api/videos:
    post:
      tags:
        - Videos
      summary: Upload a new video
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                title:
                  type: string
                description:
                  type: string
                visibility:
                  type: string
                  enum: [public, private, unlisted]
                channel:
                  type: integer
                authorizedUsers:
                  type: array
                  items:
                    type: integer
              required:
                - file
                - title
                - description
                - visibility
                - channel
      responses:
        '201':
          description: Video uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Video'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the channel owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/videos/thumbnail:
    post:
      tags:
        - Videos
      summary: Upload or update video thumbnail
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                video:
                  type: integer
                channel:
                  type: integer
              required:
                - file
                - video
                - channel
      responses:
        '200':
          description: Thumbnail uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  thumbnail:
                    type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the channel owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/videos/{id}:
    get:
      tags:
        - Videos
      summary: Get video by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Video found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Video'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - no access to video
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      tags:
        - Videos
      summary: Update video metadata
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                description:
                  type: string
                visibility:
                  type: string
                  enum: [public, private, unlisted]
                channel:
                  type: integer
      responses:
        '200':
          description: Video updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Video'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      tags:
        - Videos
      summary: Delete video
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Video deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/videos/{id}/video:
    put:
      tags:
        - Videos
      summary: Update video file
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                channel:
                  type: integer
              required:
                - file
                - channel
      responses:
        '200':
          description: Video file updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Video'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/videos/channel/{id}:
    get:
      tags:
        - Videos
      summary: Get videos by channel
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Videos retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Video'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Channel not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/videos/{id}/like:
    get:
      tags:
        - Videos
      summary: Toggle like on video
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Like toggled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  liked:
                    type: boolean
                  likes:
                    type: integer
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/videos/{id}/tags:
    put:
      tags:
        - Videos
      summary: Update video tags
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tags:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Tags updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Video'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/videos/{id}/similar:
    get:
      tags:
        - Videos
      summary: Get similar videos
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Similar videos retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Video'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/videos/{id}/views:
    get:
      tags:
        - Videos
      summary: Add view to video
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: View added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  views:
                    type: integer
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/videos/{id}/likes/day:
    get:
      tags:
        - Videos
      summary: Get likes per day for video
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Likes per day retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    date:
                      type: string
                      format: date
                    likes:
                      type: integer
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/videos/{id}/authorized-users:
    put:
      tags:
        - Videos
      summary: Update authorized users for private video
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                authorizedUsers:
                  type: array
                  items:
                    type: integer
      responses:
        '200':
          description: Authorized users updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Video'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # COMMENT ENDPOINTS
  /api/comments:
    post:
      tags:
        - Comments
      summary: Create a new comment
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                video:
                  type: integer
              required:
                - content
                - video
      responses:
        '201':
          description: Comment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/comments/video/{id}:
    get:
      tags:
        - Comments
      summary: Get comments for a video
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Comments retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/comments/{id}:
    get:
      tags:
        - Comments
      summary: Get comment by ID
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Comment found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Comment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      tags:
        - Comments
      summary: Update comment
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                video:
                  type: integer
              required:
                - content
                - video
      responses:
        '200':
          description: Comment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the author
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Comment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      tags:
        - Comments
      summary: Delete comment
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Comment deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the author
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Comment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # PLAYLIST ENDPOINTS
  /api/playlists:
    post:
      tags:
        - Playlists
      summary: Create a new playlist
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
              required:
                - name
      responses:
        '200':
          description: Playlist created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/playlists/see-later:
    get:
      tags:
        - Playlists
      summary: Get "See Later" playlist
      security:
        - BearerAuth: []
      responses:
        '200':
          description: See Later playlist retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Playlist not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/playlists/{id}:
    post:
      tags:
        - Playlists
      summary: Add video to playlist
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                video:
                  type: integer
              required:
                - video
      responses:
        '200':
          description: Video added to playlist successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Playlist or video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    get:
      tags:
        - Playlists
      summary: Get playlist by ID
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Playlist retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Playlist not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      tags:
        - Playlists
      summary: Update playlist
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
              required:
                - name
      responses:
        '200':
          description: Playlist updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Playlist not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      tags:
        - Playlists
      summary: Delete playlist
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Playlist deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Playlist not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/playlists/user/{id}:
    get:
      tags:
        - Playlists
      summary: Get playlists by user
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User playlists retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Playlist'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found or no playlists found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/playlists/{id}/video/{videoId}:
    delete:
      tags:
        - Playlists
      summary: Remove video from playlist
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
        - name: videoId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Video removed from playlist successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Playlist or video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # SEARCH ENDPOINTS
  /api/search:
    get:
      tags:
        - Search
      summary: Search videos and channels
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query
        - name: type
          in: query
          schema:
            type: string
            enum: [videos, channel]
            default: videos
          description: Type of search (videos or channel)
      responses:
        '200':
          description: Search results retrieved successfully
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/Video'
                  - type: array
                    items:
                      $ref: '#/components/schemas/Channel'
        '400':
          description: Bad request - query parameter required or invalid type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # RECOMMENDATION ENDPOINTS
  /api/recommendations:
    get:
      tags:
        - Recommendations
      summary: Get personalized recommendations
      responses:
        '200':
          description: Recommendations retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Video'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/recommendations/trending:
    get:
      tags:
        - Recommendations
      summary: Get trending videos
      responses:
        '200':
          description: Trending videos retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Video'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/recommendations/creators:
    get:
      tags:
        - Recommendations
      summary: Get top creators
      responses:
        '200':
          description: Top creators retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Channel'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # MEDIA ENDPOINTS
  /api/media/profile/{file}:
    get:
      tags:
        - Media
      summary: Get profile picture
      parameters:
        - name: file
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Profile picture retrieved successfully
          content:
            image/*:
              schema:
                type: string
                format: binary
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/media/video/{file}:
    get:
      tags:
        - Media
      summary: Get video file
      parameters:
        - name: file
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Video file retrieved successfully
          content:
            video/*:
              schema:
                type: string
                format: binary
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/media/thumbnail/{file}:
    get:
      tags:
        - Media
      summary: Get video thumbnail
      parameters:
        - name: file
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Thumbnail retrieved successfully
          content:
            image/*:
              schema:
                type: string
                format: binary
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # OAUTH ENDPOINTS
  /api/oauth/github:
    get:
      tags:
        - OAuth
      summary: Initiate GitHub OAuth login
      responses:
        '302':
          description: Redirect to GitHub OAuth
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/oauth/callback:
    get:
      tags:
        - OAuth
      summary: GitHub OAuth callback
      parameters:
        - name: code
          in: query
          required: true
          schema:
            type: string
        - name: state
          in: query
          schema:
            type: string
      responses:
        '302':
          description: Redirect after successful authentication
        '400':
          description: OAuth error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/oauth/me:
    get:
      tags:
        - OAuth
      summary: Get current authenticated user info
      security:
        - BearerAuth: []
      responses:
        '200':
          description: User info retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'