665 lines
18 KiB
YAML
665 lines
18 KiB
YAML
openapi: 3.0.4
|
||
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
|
||
schema:
|
||
type: boolean
|
||
default: true
|
||
- in: query
|
||
name: word
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: status
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/TitleStatus'
|
||
description: List of title statuses to filter
|
||
style: form
|
||
explode: false
|
||
- 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 with cursor
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/Title'
|
||
description: List of titles
|
||
cursor:
|
||
$ref: '#/components/schemas/CursorObj'
|
||
required:
|
||
- data
|
||
- cursor
|
||
'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'
|
||
'204':
|
||
description: No title found
|
||
'400':
|
||
description: Request params are not correct
|
||
'404':
|
||
description: Title not found
|
||
'500':
|
||
description: Unknown server error
|
||
'/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'
|
||
'400':
|
||
description: Request params are not correct
|
||
'404':
|
||
description: User not found
|
||
'500':
|
||
description: Unknown server error
|
||
patch:
|
||
summary: Partially update a user account
|
||
description: |
|
||
Update selected user profile fields (excluding password).
|
||
Password updates must be done via the dedicated auth-service (`/auth/`).
|
||
Fields not provided in the request body remain unchanged.
|
||
operationId: updateUser
|
||
parameters:
|
||
- name: user_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
description: User ID (primary key)
|
||
example: 123
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
avatar_id:
|
||
type: integer
|
||
format: int64
|
||
nullable: true
|
||
description: ID of the user avatar (references `images.id`); set to `null` to remove avatar
|
||
example: 42
|
||
mail:
|
||
type: string
|
||
format: email
|
||
pattern: '^[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+\\.[a-zA-Z0-9_-]+$'
|
||
description: User email (must be unique and valid)
|
||
example: john.doe.updated@example.com
|
||
nickname:
|
||
type: string
|
||
pattern: '^[a-zA-Z0-9_-]{3,16}$'
|
||
description: 'Username (alphanumeric + `_` or `-`, 3–16 chars)'
|
||
maxLength: 16
|
||
minLength: 3
|
||
example: john_doe_43
|
||
disp_name:
|
||
type: string
|
||
description: Display name
|
||
maxLength: 32
|
||
example: John Smith
|
||
user_desc:
|
||
type: string
|
||
description: User description / bio
|
||
maxLength: 512
|
||
example: Just a curious developer.
|
||
additionalProperties: false
|
||
description: Only provided fields are updated. Omitted fields remain unchanged.
|
||
responses:
|
||
'200':
|
||
description: User updated successfully. Returns updated user representation (excluding sensitive fields).
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/User'
|
||
'400':
|
||
description: 'Invalid input (e.g., validation failed, nickname/email conflict, malformed JSON)'
|
||
'401':
|
||
description: Unauthorized — missing or invalid authentication token
|
||
'403':
|
||
description: 'Forbidden — user is not allowed to modify this resource (e.g., not own profile & no admin rights)'
|
||
'404':
|
||
description: User not found
|
||
'409':
|
||
description: 'Conflict — e.g., requested `nickname` or `mail` already taken by another user'
|
||
'422':
|
||
description: 'Unprocessable Entity — semantic errors not caught by schema (e.g., invalid `avatar_id`)'
|
||
'500':
|
||
description: Unknown server error
|
||
'/users/{user_id}/titles':
|
||
get:
|
||
summary: Get user titles
|
||
parameters:
|
||
- $ref: '#/components/parameters/cursor'
|
||
- $ref: '#/components/parameters/title_sort'
|
||
- in: path
|
||
name: user_id
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: sort_forward
|
||
schema:
|
||
type: boolean
|
||
default: true
|
||
- in: query
|
||
name: word
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: status
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/TitleStatus'
|
||
description: List of title statuses to filter
|
||
style: form
|
||
explode: false
|
||
- in: query
|
||
name: watch_status
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/UserTitleStatus'
|
||
style: form
|
||
explode: false
|
||
- in: query
|
||
name: rating
|
||
schema:
|
||
type: number
|
||
format: double
|
||
- in: query
|
||
name: my_rate
|
||
schema:
|
||
type: integer
|
||
format: int32
|
||
- 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: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/UserTitle'
|
||
cursor:
|
||
$ref: '#/components/schemas/CursorObj'
|
||
required:
|
||
- data
|
||
- cursor
|
||
'204':
|
||
description: No titles found
|
||
'400':
|
||
description: Request params are not correct
|
||
'404':
|
||
description: User not found
|
||
'500':
|
||
description: Unknown server error
|
||
post:
|
||
summary: Add a title to a user
|
||
description: 'User adding title to list af watched, status required'
|
||
operationId: addUserTitle
|
||
parameters:
|
||
- name: user_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
description: ID of the user to assign the title to
|
||
example: 123
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- title_id
|
||
- status
|
||
properties:
|
||
title_id:
|
||
type: integer
|
||
format: int64
|
||
status:
|
||
$ref: '#/components/schemas/UserTitleStatus'
|
||
rate:
|
||
type: integer
|
||
format: int32
|
||
responses:
|
||
'200':
|
||
description: Title successfully added to user
|
||
content:
|
||
application/json:
|
||
schema:
|
||
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: false
|
||
'400':
|
||
description: 'Invalid request body (missing fields, invalid types, etc.)'
|
||
'401':
|
||
description: Unauthorized — missing or invalid auth token
|
||
'403':
|
||
description: Forbidden — user not allowed to assign titles to this user
|
||
'404':
|
||
description: User or Title not found
|
||
'409':
|
||
description: Conflict — title already assigned to user (if applicable)
|
||
'500':
|
||
description: Internal server error
|
||
patch:
|
||
summary: Update a usertitle
|
||
description: User updating title list of watched
|
||
operationId: updateUserTitle
|
||
parameters:
|
||
- name: user_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
description: ID of the user to assign the title to
|
||
example: 123
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- title_id
|
||
properties:
|
||
title_id:
|
||
type: integer
|
||
format: int64
|
||
status:
|
||
$ref: '#/components/schemas/UserTitleStatus'
|
||
rate:
|
||
type: integer
|
||
format: int32
|
||
responses:
|
||
'200':
|
||
description: Title successfully updated
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/paths/~1users~1%7Buser_id%7D~1titles/post/responses/200/content/application~1json/schema'
|
||
'400':
|
||
description: 'Invalid request body (missing fields, invalid types, etc.)'
|
||
'401':
|
||
description: Unauthorized — missing or invalid auth token
|
||
'403':
|
||
description: Forbidden — user not allowed to update title
|
||
'404':
|
||
description: User or Title not found
|
||
'500':
|
||
description: Internal server error
|
||
components:
|
||
parameters:
|
||
cursor:
|
||
in: query
|
||
name: cursor
|
||
required: false
|
||
schema:
|
||
type: string
|
||
title_sort:
|
||
in: query
|
||
name: sort
|
||
required: false
|
||
schema:
|
||
$ref: '#/components/schemas/TitleSort'
|
||
schemas:
|
||
CursorObj:
|
||
type: object
|
||
required:
|
||
- id
|
||
properties:
|
||
id:
|
||
type: integer
|
||
format: int64
|
||
param:
|
||
type: string
|
||
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
|
||
description: Image storage type
|
||
enum:
|
||
- s3
|
||
- local
|
||
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
|
||
image:
|
||
$ref: '#/components/schemas/Image'
|
||
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
|
||
UserTitle:
|
||
type: object
|
||
required:
|
||
- user_id
|
||
- title_id
|
||
- status
|
||
properties:
|
||
user_id:
|
||
type: integer
|
||
format: int64
|
||
title:
|
||
$ref: '#/components/schemas/Title'
|
||
status:
|
||
$ref: '#/components/schemas/UserTitleStatus'
|
||
rate:
|
||
type: integer
|
||
format: int32
|
||
review_id:
|
||
type: integer
|
||
format: int64
|
||
ctime:
|
||
type: string
|
||
format: date-time
|