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