openapi: 3.1.1
info:
  title: Titles, Users, Reviews, Tags, and Media API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /title:
    get:
      summary: Get titles
      parameters:
        - in: query
          name: query
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
        - in: query
          name: fields
          schema:
            type: string
            default: all
      responses:
        '200':
          description: List of titles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Title'
        '204':
          description: No titles found

  /title/{title_id}:
    get:
      summary: Get title description
      parameters:
        - in: path
          name: title_id
          required: true
          schema:
            type: string
        - in: query
          name: fields
          schema:
            type: string
            default: all
      responses:
        '200':
          description: Title description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Title'
        '404':
          description: Title not found

    patch:
      summary: Update title info
      parameters:
        - in: path
          name: title_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Title'
      responses:
        '200':
          description: Update result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  user_json:
                    $ref: '#/components/schemas/User'

  /title/{title_id}/reviews:
    get:
      summary: Get title reviews
      parameters:
        - in: path
          name: title_id
          required: true
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of reviews
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Review'
        '204':
          description: No reviews found

  /users/{user_id}:
    get:
      summary: Get user info
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: string
        - in: query
          name: fields
          schema:
            type: string
            default: all
      responses:
        '200':
          description: User info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found

    patch:
      summary: Update user
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Update result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string

    delete:
      summary: Delete user
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Delete result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string

  /users:
    get:
      summary: Search user
      parameters:
        - in: query
          name: query
          schema:
            type: string
        - in: query
          name: fields
          schema:
            type: string
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

    post:
      summary: Add new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Add result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  user_json:
                    $ref: '#/components/schemas/User'

  /users/{user_id}/titles:
    get:
      summary: Get user titles
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: string
        - in: query
          name: query
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
        - in: query
          name: fields
          schema:
            type: string
            default: all
      responses:
        '200':
          description: List of user titles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserTitle'
        '204':
          description: No titles found

    post:
      summary: Add user title
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title_id:
                  type: string
                status:
                  type: string
      responses:
        '200':
          description: Add result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string

    patch:
      summary: Update user title
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserTitle'
      responses:
        '200':
          description: Update result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string

    delete:
      summary: Delete user title
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: string
        - in: query
          name: title_id
          schema:
            type: string
      responses:
        '200':
          description: Delete result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string

  /users/{user_id}/reviews:
    get:
      summary: Get user reviews
      parameters:
        - in: path
          name: user_id
          required: true
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of reviews
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Review'

  /reviews:
    post:
      summary: Add review
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Review'
      responses:
        '200':
          description: Add result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string

  /reviews/{review_id}:
    patch:
      summary: Update review
      parameters:
        - in: path
          name: review_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Review'
      responses:
        '200':
          description: Update result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
    delete:
      summary: Delete review
      parameters:
        - in: path
          name: review_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Delete result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string

  /tags:
    get:
      summary: Get tags
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
        - in: query
          name: fields
          schema:
            type: string
      responses:
        '200':
          description: List of tags
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'

  /media:
    post:
      summary: Upload image
      responses:
        '200':
          description: Upload result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  image_id:
                    type: string

    get:
      summary: Get image path
      parameters:
        - in: query
          name: image_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Image path
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  image_path:
                    type: string

components:
  schemas:
    Title:
      type: object
      additionalProperties: true
    User:
      type: object
      properties:
        user_id:
          type: integer
          format: int32
          description: Unique user ID (primary key)
          example: 1
        avatar_id:
          type: integer
          format: int32
          description: ID of the user avatar (references images table)
          nullable: true
          example: null
        mail:
          type: string
          format: email
          description: User email
          example: "john.doe@example.com"
        nickname:
          type: string
          description: Username (alphanumeric + _ or -)
          maxLength: 16
          example: "john_doe_42"
        disp_name:
          type: string
          description: Display name
          maxLength: 32
          example: "John Doe"
        user_desc:
          type: string
          description: User description
          maxLength: 512
          example: "Just a regular user."
        creation_date:
          type: string
          format: date-time
          description: Timestamp when the user was created
          example: "2025-10-10T23:45:47.908073Z"
      required:
        - user_id
        - nickname
        - creation_date
    UserTitle:
      type: object
      additionalProperties: true
    Review:
      type: object
      additionalProperties: true
    Tag:
      type: object
      additionalProperties: true