openapi: 3.1.1
info:
  title: Titles, Users, Reviews, Tags, and Media API
  version: 1.0.0

servers:
  - url: /api/v1

paths:
  /titles:
    get:
      summary: Get titles
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/title_sort'
        - in: query
          name: sort_forward
          default: true
          schema:
            type: boolean
        - in: query
          name: word
          schema:
            type: string
        - in: query
          name: status
          schema:
            $ref: '#/components/schemas/TitleStatus'
        - in: query
          name: rating
          schema:
            type: number
            format: double
        - in: query
          name: release_year
          schema:
            type: integer
            format: int32
        - in: query
          name: release_season
          schema:
            $ref: '#/components/schemas/ReleaseSeason'
        - in: query
          name: limit
          schema:
            type: integer
            format: int32
            default: 10
        - in: query
          name: offset
          schema:
            type: integer
            format: int32
            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
        '400':
          description: Request params are not correct
        '500':
          description: Unknown server error

  /titles/{title_id}:
    get:
      summary: Get title description
      parameters:
        - in: path
          name: title_id
          required: true
          schema:
            type: integer
            format: int64
        - 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
        '400':
          description: Request params are not correct
        '500':
          description: Unknown server error
        '204':
          description: No title 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'

#   /titles/{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
        '400':
          description: Request params are not correct
        '500':
          description: Unknown server error

    # 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:
        - $ref: '#/components/parameters/cursor'
        - in: path
          name: user_id
          required: true
          schema:
            type: string
        - in: query
          name: word
          schema:
            type: string
        - in: query
          name: status
          schema:
            $ref: '#/components/schemas/TitleStatus'
        - in: query
          name: watch_status
          schema:
            $ref: '#/components/schemas/UserTitleStatus'
        - in: query
          name: rating
          schema:
            type: number
            format: double
        - in: query
          name: release_year
          schema:
            type: integer
            format: int32
        - in: query
          name: release_season
          schema:
            $ref: '#/components/schemas/ReleaseSeason'
        - in: query
          name: limit
          schema:
            type: integer
            format: int32
            default: 10
        - 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
        '400':
          description: Request params are not correct
        '500':
          description: Unknown server error

#     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:
  parameters:
    cursor: # example base64( {id: 1, param: 2019})
        in: query
        name: cursor
        required: false
        schema:
          type: string
    
    title_sort:
        in: query
        name: sort
        required: false
        schema: 
          $ref: '#/components/schemas/TitleSort'

  schemas:
    TitleSort:
      type: string
      description: Title sort order
      default: id
      enum:
        - id
        - year
        - rating
        - views

    Image:
      type: object
      properties:
        id:
          type: integer
          format: int64
        storage_type:
          type: string
        image_path:
          type: string

    TitleStatus:
      type: string
      description: Title status
      enum:
        - finished
        - ongoing
        - planned

    ReleaseSeason:
      type: string
      description: Title release season
      enum:
        - winter
        - spring
        - summer
        - fall

    UserTitleStatus:
      type: string
      description: User's title status
      enum:
        - finished
        - planned
        - dropped
        - in-progress

    Review:
      type: object
      additionalProperties: true

    Tag:
      type: object
      description: "A localized tag: keys are language codes (ISO 639-1), values are tag names"
      additionalProperties:
        type: string
      example:
        en: "Shojo"
        ru: "Сёдзё"
        ja: "少女"

    Tags:
      type: array
      description: "Array of localized tags"
      items:
        $ref: '#/components/schemas/Tag'
      example:
        - en: "Shojo"
          ru: "Сёдзё"
          ja: "少女"
        - en: "Shounen"
          ru: "Сёнен"
          ja: "少年"

    Studio:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        poster:
          $ref: '#/components/schemas/Image'
        description:
          type: string


    Title:
      type: object
      required:
        - id
        - title_names
        - tags
      properties:
        id:
          type: integer
          format: int64
          description: Unique title ID (primary key)
          example: 1
        title_names:
          type: object
          description: "Localized titles. Key = language (ISO 639-1), value = list of names"
          additionalProperties:
            type: array
            items:
              type: string
              example: "Attack on Titan"
            minItems: 1
            example: ["Attack on Titan", "AoT"]
          example:
            en: ["Attack on Titan", "AoT"]
            ru: ["Атака титанов", "Титаны"]
            ja: ["進撃の巨人"]
        studio:
          $ref: '#/components/schemas/Studio'
        tags:
          $ref: '#/components/schemas/Tags'
        poster:
          $ref: '#/components/schemas/Image'
        title_status:
          $ref: '#/components/schemas/TitleStatus'
        rating:
          type: number
          format: double
        rating_count:
          type: integer
          format: int32
        release_year:
          type: integer
          format: int32
        release_season:
          $ref: '#/components/schemas/ReleaseSeason'
        episodes_aired:
          type: integer
          format: int32
        episodes_all:
          type: integer
          format: int32
        episodes_len:
          type: object
          additionalProperties:
            type: number
            format: double
      additionalProperties: true

    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique user ID (primary key)
          example: 1
        avatar_id:
          type: integer
          format: int64
          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
      required:
        - user_id
        - title_id
        - status
      properties:
        user_id:
          type: integer
          format: int64
        title_id:
          type: integer
          format: int64
        status:
          $ref: '#/components/schemas/UserTitleStatus'
        rate:
          type: integer
          format: int32
        review_id:
          type: integer
          format: int64
        ctime:
          type: string
          format: date-time
      additionalProperties: true