837 lines
20 KiB
YAML
837 lines
20 KiB
YAML
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
|