nihonium/nyanimedb
1
0
Fork 1
Code Issues 12 Pull requests Releases Packages 3 Activity Actions

Merge branch 'dev' into dev-karas

Browse source 
Need to update the openapi documentation.
This commit is contained in:
Kirill 2025-12-05 01:42:08 +03:00
commit 4ca8b19adb
119 changed files with 11518 additions and 2099 deletions
Download patch file Download diff file Expand all files Collapse all files

6
api/_build/oapi-codegen.yaml Normal file
View file

@ -0,0 +1,6 @@
package: oapi
generate:
strict-server: true
gin-server: true
models: true
output: api/api.gen.go

750
api/_build/openapi.yaml Normal file
View file

@ -0,0 +1,750 @@
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'
- name: sort_forward
in: query
schema:
type: boolean
default: true
- name: ext_search
in: query
schema:
type: boolean
default: false
- name: word
in: query
schema:
type: string
- name: status
in: query
description: List of title statuses to filter
schema:
type: array
items:
$ref: '#/components/schemas/TitleStatus'
explode: false
style: form
- name: rating
in: query
schema:
type: number
format: double
- name: release_year
in: query
schema:
type: integer
format: int32
- name: release_season
in: query
schema:
$ref: '#/components/schemas/ReleaseSeason'
- name: limit
in: query
schema:
type: integer
format: int32
default: 10
- name: offset
in: query
schema:
type: integer
format: int32
default: 0
- name: fields
in: query
schema:
type: string
default: all
responses:
'200':
description: List of titles with cursor
content:
application/json:
schema:
type: object
properties:
data:
description: List of titles
type: array
items:
$ref: '#/components/schemas/Title'
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:
operationId: getTitle
summary: Get title description
parameters:
- name: title_id
in: path
required: true
schema:
type: integer
format: int64
- name: fields
in: query
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
security:
- JwtAuthCookies: []
'/users/{user_id}':
get:
operationId: getUsersId
summary: Get user info
parameters:
- name: user_id
in: path
required: true
schema:
type: string
- name: fields
in: query
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:
operationId: updateUser
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.
parameters:
- name: user_id
in: path
description: User ID (primary key)
required: true
schema:
type: integer
format: int64
example: 123
requestBody:
required: true
content:
application/json:
schema:
description: Only provided fields are updated. Omitted fields remain unchanged.
type: object
properties:
avatar_id:
description: ID of the user avatar (references `images.id`); set to `null` to remove avatar
type: integer
format: int64
example: 42
nullable: true
mail:
description: User email (must be unique and valid)
type: string
format: email
example: john.doe.updated@example.com
pattern: '^[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+\\.[a-zA-Z0-9_-]+$'
nickname:
description: 'Username (alphanumeric + `_` or `-`, 3–16 chars)'
type: string
example: john_doe_43
maxLength: 16
minLength: 3
pattern: '^[a-zA-Z0-9_-]{3,16}$'
disp_name:
description: Display name
type: string
example: John Smith
maxLength: 32
user_desc:
description: User description / bio
type: string
example: Just a curious developer.
maxLength: 512
additionalProperties: false
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
security:
- XsrfAuthHeader: []
'/users/{user_id}/titles':
get:
operationId: getUserTitles
summary: Get user titles
parameters:
- $ref: '#/components/parameters/cursor'
- $ref: '#/components/parameters/title_sort'
- name: user_id
in: path
required: true
schema:
type: string
- name: sort_forward
in: query
schema:
type: boolean
default: true
- name: word
in: query
schema:
type: string
- name: status
in: query
description: List of title statuses to filter
schema:
type: array
items:
$ref: '#/components/schemas/TitleStatus'
explode: false
style: form
- name: watch_status
in: query
schema:
type: array
items:
$ref: '#/components/schemas/UserTitleStatus'
explode: false
style: form
- name: rating
in: query
schema:
type: number
format: double
- name: my_rate
in: query
schema:
type: integer
format: int32
- name: release_year
in: query
schema:
type: integer
format: int32
- name: release_season
in: query
schema:
$ref: '#/components/schemas/ReleaseSeason'
- name: limit
in: query
schema:
type: integer
format: int32
default: 10
- name: fields
in: query
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:
operationId: addUserTitle
summary: Add a title to a user
description: 'User adding title to list af watched, status required'
parameters:
- name: user_id
in: path
description: ID of the user to assign the title to
required: true
schema:
type: integer
format: int64
example: 123
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title_id:
type: integer
format: int64
status:
$ref: '#/components/schemas/UserTitleStatus'
rate:
type: integer
format: int32
required:
- title_id
- status
responses:
'200':
description: Title successfully added to user
content:
application/json:
schema:
$ref: '#/components/schemas/UserTitleMini'
'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
'/users/{user_id}/titles/{title_id}':
get:
operationId: getUserTitle
summary: Get user title
parameters:
- name: user_id
in: path
required: true
schema:
type: integer
format: int64
- name: title_id
in: path
required: true
schema:
type: integer
format: int64
responses:
'200':
description: User titles
content:
application/json:
schema:
$ref: '#/components/schemas/UserTitleMini'
'204':
description: No user title found
'400':
description: Request params are not correct
'404':
description: User or title not found
'500':
description: Unknown server error
patch:
operationId: updateUserTitle
summary: Update a usertitle
description: User updating title list of watched
parameters:
- name: user_id
in: path
required: true
schema:
type: integer
format: int64
- name: title_id
in: path
required: true
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/UserTitleStatus'
rate:
type: integer
format: int32
responses:
'200':
description: Title successfully updated
content:
application/json:
schema:
$ref: '#/components/schemas/UserTitleMini'
'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
security:
- XsrfAuthHeader: []
delete:
operationId: deleteUserTitle
summary: Delete a usertitle
description: User deleting title from list of watched
parameters:
- name: user_id
in: path
required: true
schema:
type: integer
format: int64
- name: title_id
in: path
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Title successfully deleted
'401':
description: Unauthorized — missing or invalid auth token
'403':
description: Forbidden — user not allowed to delete title
'404':
description: User or Title not found
'500':
description: Internal server error
security:
- XsrfAuthHeader: []
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:
TitleSort:
description: Title sort order
type: string
default: id
enum:
- id
- year
- rating
- views
TitleStatus:
description: Title status
type: string
enum:
- finished
- ongoing
- planned
ReleaseSeason:
description: Title release season
type: string
enum:
- winter
- spring
- summer
- fall
StorageType:
description: Image storage type
type: string
enum:
- s3
- local
Image:
type: object
properties:
id:
type: integer
format: int64
storage_type:
$ref: '#/components/schemas/StorageType'
image_path:
type: string
Studio:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
poster:
$ref: '#/components/schemas/Image'
description:
type: string
required:
- id
- name
Tag:
description: 'A localized tag: keys are language codes (ISO 639-1), values are tag names'
type: object
example:
en: Shojo
ru: Сёдзё
ja: 少女
additionalProperties:
type: string
Tags:
description: Array of localized tags
type: array
items:
$ref: '#/components/schemas/Tag'
example:
- en: Shojo
ru: Сёдзё
ja: 少女
- en: Shounen
ru: Сёнен
ja: 少年
Title:
type: object
properties:
id:
description: Unique title ID (primary key)
type: integer
format: int64
example: 1
title_names:
description: 'Localized titles. Key = language (ISO 639-1), value = list of names'
type: object
example:
en:
- Attack on Titan
- AoT
ru:
- Атака титанов
- Титаны
ja:
- 進撃の巨人
additionalProperties:
type: array
items:
type: string
example: Attack on Titan
minItems: 1
example:
- Attack on Titan
- AoT
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
required:
- id
- title_names
- tags
CursorObj:
type: object
properties:
id:
type: integer
format: int64
param:
type: string
required:
- id
User:
type: object
properties:
id:
description: Unique user ID (primary key)
type: integer
format: int64
example: 1
image:
$ref: '#/components/schemas/Image'
mail:
description: User email
type: string
format: email
example: john.doe@example.com
nickname:
description: Username (alphanumeric + _ or -)
type: string
example: john_doe_42
maxLength: 16
disp_name:
description: Display name
type: string
example: John Doe
maxLength: 32
user_desc:
description: User description
type: string
example: Just a regular user.
maxLength: 512
creation_date:
description: Timestamp when the user was created
type: string
format: date-time
example: '2025-10-10T23:45:47.908073Z'
required:
- user_id
- nickname
UserTitleStatus:
description: User's title status
type: string
enum:
- finished
- planned
- dropped
- in-progress
UserTitle:
type: object
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
required:
- user_id
- title_id
- status
UserTitleMini:
type: object
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
required:
- user_id
- title_id
- status
Review:
type: object
additionalProperties: true
securitySchemes:
XsrfAuthHeader:
type: apiKey
in: header
name: X-XSRF-TOKEN
description: |
Anti-CSRF token. Must match the `XSRF-TOKEN` cookie.
Required for all state-changing requests (POST/PUT/PATCH/DELETE).

1492
api/api.gen.go
View file

File diff suppressed because it is too large Load diff

763
api/openapi.yaml
View file

@ -1,4 +1,4 @@
openapi: 3.1.1
openapi: 3.0.4
info:
title: Titles, Users, Reviews, Tags, and Media API
version: 1.0.0
@ -7,754 +7,21 @@ servers:
- url: /api/v1
paths:
/title:
get:
summary: Get titles
parameters:
- 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
/title/{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'
# /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
/titles:
$ref: "./paths/titles.yaml"
/titles/{title_id}:
$ref: "./paths/titles-id.yaml"
/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:
# - 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
$ref: "./paths/users-id.yaml"
/users/{user_id}/titles:
$ref: "./paths/users-id-titles.yaml"
/users/{user_id}/titles/{title_id}:
$ref: "./paths/users-id-titles-id.yaml"
components:
parameters:
$ref: "./parameters/_index.yaml"
schemas:
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
additionalProperties: true
$ref: "./schemas/_index.yaml"
securitySchemes:
$ref: "./securitySchemes/_index.yaml"

4
api/parameters/_index.yaml Normal file
View file

@ -0,0 +1,4 @@
cursor:
$ref: "./cursor.yaml"
title_sort:
$ref: "./title_sort.yaml"

5
api/parameters/cursor.yaml Normal file
View file

@ -0,0 +1,5 @@
in: query
name: cursor
required: false
schema:
type: string

5
api/parameters/title_sort.yaml Normal file
View file

@ -0,0 +1,5 @@
in: query
name: sort
required: false
schema:
$ref: '../schemas/TitleSort.yaml'

32
api/paths/titles-id.yaml Normal file
View file

@ -0,0 +1,32 @@
get:
summary: Get title description
security:
- JwtAuthCookies: []
operationId: getTitle
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: "../schemas/Title.yaml"
'404':
description: Title not found
'400':
description: Request params are not correct
'500':
description: Unknown server error
'204':
description: No title found

83
api/paths/titles.yaml Normal file
View file

@ -0,0 +1,83 @@
get:
summary: Get titles
parameters:
- $ref: "../parameters/cursor.yaml"
- $ref: "../parameters/title_sort.yaml"
- in: query
name: sort_forward
schema:
type: boolean
default: true
- in: query
name: ext_search
schema:
type: boolean
default: false
- in: query
name: word
schema:
type: string
- in: query
name: status
schema:
type: array
items:
$ref: '../schemas/enums/TitleStatus.yaml'
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: '../schemas/enums/ReleaseSeason.yaml'
- 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: '../schemas/Title.yaml'
description: List of titles
cursor:
$ref: '../schemas/CursorObj.yaml'
required:
- data
- cursor
'204':
description: No titles found
'400':
description: Request params are not correct
'500':
description: Unknown server error

111
api/paths/users-id-titles-id.yaml Normal file
View file

@ -0,0 +1,111 @@
get:
summary: Get user title
operationId: getUserTitle
parameters:
- in: path
name: user_id
required: true
schema:
type: integer
format: int64
- in: path
name: title_id
required: true
schema:
type: integer
format: int64
responses:
'200':
description: User titles
content:
application/json:
schema:
$ref: '../schemas/UserTitleMini.yaml'
'204':
description: No user title found
'400':
description: Request params are not correct
'404':
description: User or title not found
'500':
description: Unknown server error
patch:
summary: Update a usertitle
description: User updating title list of watched
operationId: updateUserTitle
security:
- XsrfAuthHeader: []
parameters:
- in: path
name: user_id
required: true
schema:
type: integer
format: int64
- in: path
name: title_id
required: true
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
status:
$ref: '../schemas/enums/UserTitleStatus.yaml'
rate:
type: integer
format: int32
responses:
'200':
description: Title successfully updated
content:
application/json:
schema:
$ref: '../schemas/UserTitleMini.yaml'
'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
delete:
summary: Delete a usertitle
description: User deleting title from list of watched
operationId: deleteUserTitle
security:
- XsrfAuthHeader: []
parameters:
- in: path
name: user_id
required: true
schema:
type: integer
format: int64
- in: path
name: title_id
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Title successfully deleted
'401':
description: Unauthorized — missing or invalid auth token
'403':
description: Forbidden — user not allowed to delete title
'404':
description: User or Title not found
'500':
description: Internal server error

143
api/paths/users-id-titles.yaml Normal file
View file

@ -0,0 +1,143 @@
get:
summary: Get user titles
operationId: getUserTitles
parameters:
- $ref: '../parameters/cursor.yaml'
- $ref: "../parameters/title_sort.yaml"
- 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: '../schemas/enums/TitleStatus.yaml'
description: List of title statuses to filter
style: form
explode: false
- in: query
name: watch_status
schema:
type: array
items:
$ref: '../schemas/enums/UserTitleStatus.yaml'
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: '../schemas/enums/ReleaseSeason.yaml'
- 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: '../schemas/UserTitle.yaml'
cursor:
$ref: '../schemas/CursorObj.yaml'
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: '../schemas/enums/UserTitleStatus.yaml'
rate:
type: integer
format: int32
responses:
'200':
description: Title successfully added to user
content:
application/json:
schema:
$ref: '../schemas/UserTitleMini.yaml'
'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

106
api/paths/users-id.yaml Normal file
View file

@ -0,0 +1,106 @@
get:
summary: Get user info
operationId: getUsersId
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: '../schemas/User.yaml'
'404':
description: User not found
'400':
description: Request params are not correct
'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
security:
- XsrfAuthHeader: []
parameters:
# - $ref: '../parameters/xsrf_token_header.yaml'
- 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: '../schemas/User.yaml'
'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

9
api/schemas/CursorObj.yaml Normal file
View file

@ -0,0 +1,9 @@
type: object
required:
- id
properties:
id:
type: integer
format: int64
param:
type: string

10
api/schemas/Image.yaml Normal file
View file

@ -0,0 +1,10 @@
type: object
properties:
# id выпиливаем
id:
type: integer
format: int64
storage_type:
$ref: './enums/StorageType.yaml'
image_path:
type: string

7
api/schemas/JWTAuth.yaml Normal file
View file

@ -0,0 +1,7 @@
# type: apiKey
# in: cookie
# name: access_token
# scheme: bearer
# bearerFormat: JWT
# description: |
# JWT access token sent in `Cookie: access_token=...`.

2
api/schemas/Review.yaml Normal file
View file

@ -0,0 +1,2 @@
type: object
additionalProperties: true

15
api/schemas/Studio.yaml Normal file
View file

@ -0,0 +1,15 @@
type: object
required:
- id
- name
properties:
# id не нужен
id:
type: integer
format: int64
name:
type: string
poster:
$ref: ./Image.yaml
description:
type: string

8
api/schemas/Tag.yaml Normal file
View file

@ -0,0 +1,8 @@
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: 少女

11
api/schemas/Tags.yaml Normal file
View file

@ -0,0 +1,11 @@
type: array
description: Array of localized tags
items:
$ref: ./Tag.yaml
example:
- en: Shojo
ru: Сёдзё
ja: 少女
- en: Shounen
ru: Сёнен
ja: 少年

62
api/schemas/Title.yaml Normal file
View file

@ -0,0 +1,62 @@
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: ./Studio.yaml
tags:
$ref: ./Tags.yaml
poster:
$ref: ./Image.yaml
title_status:
$ref: ./enums/TitleStatus.yaml
rating:
type: number
format: double
rating_count:
type: integer
format: int32
release_year:
type: integer
format: int32
release_season:
$ref: ./enums/ReleaseSeason.yaml
episodes_aired:
type: integer
format: int32
episodes_all:
type: integer
format: int32
episodes_len:
type: object
additionalProperties:
type: number
format: double

8
api/schemas/TitleSort.yaml Normal file
View file

@ -0,0 +1,8 @@
type: string
description: Title sort order
default: id
enum:
- id
- year
- rating
- views

37
api/schemas/User.yaml Normal file
View file

@ -0,0 +1,37 @@
type: object
properties:
id:
type: integer
format: int64
description: Unique user ID (primary key)
example: 1
image:
$ref: '../schemas/Image.yaml'
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

22
api/schemas/UserTitle.yaml Normal file
View file

@ -0,0 +1,22 @@
type: object
required:
- user_id
- title_id
- status
properties:
user_id:
type: integer
format: int64
title:
$ref: ./Title.yaml
status:
$ref: ./enums/UserTitleStatus.yaml
rate:
type: integer
format: int32
review_id:
type: integer
format: int64
ctime:
type: string
format: date-time

23
api/schemas/UserTitleMini.yaml Normal file
View file

@ -0,0 +1,23 @@
type: object
required:
- user_id
- title_id
- status
properties:
user_id:
type: integer
format: int64
title_id:
type: integer
format: int64
status:
$ref: ./enums/UserTitleStatus.yaml
rate:
type: integer
format: int32
review_id:
type: integer
format: int64
ctime:
type: string
format: date-time

28
api/schemas/_index.yaml Normal file
View file

@ -0,0 +1,28 @@
CursorObj:
$ref: "./CursorObj.yaml"
TitleSort:
$ref: "./TitleSort.yaml"
Image:
$ref: "./Image.yaml"
TitleStatus:
$ref: "./enums/TitleStatus.yaml"
ReleaseSeason:
$ref: "./enums/ReleaseSeason.yaml"
UserTitleStatus:
$ref: "./enums/UserTitleStatus.yaml"
Review:
$ref: "./Review.yaml"
Tag:
$ref: "./Tag.yaml"
Tags:
$ref: "./Tags.yaml"
Studio:
$ref: "./Studio.yaml"
Title:
$ref: "./Title.yaml"
User:
$ref: "./User.yaml"
UserTitle:
$ref: "./UserTitle.yaml"
# JwtAuth:
# $ref: "./JWTAuth.yaml"

7
api/schemas/enums/ReleaseSeason.yaml Normal file
View file

@ -0,0 +1,7 @@
type: string
description: Title release season
enum:
- winter
- spring
- summer
- fall

5
api/schemas/enums/StorageType.yaml Normal file
View file

@ -0,0 +1,5 @@
type: string
description: Image storage type
enum:
- s3
- local

6
api/schemas/enums/TitleStatus.yaml Normal file
View file

@ -0,0 +1,6 @@
type: string
description: Title status
enum:
- finished
- ongoing
- planned

7
api/schemas/enums/UserTitleStatus.yaml Normal file
View file

@ -0,0 +1,7 @@
type: string
description: User's title status
enum:
- finished
- planned
- dropped
- in-progress

26
api/schemas/updateUser.yaml Normal file
View file

@ -0,0 +1,26 @@
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
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.

11
api/securitySchemes/_index.yaml Normal file
View file

@ -0,0 +1,11 @@
# accessToken:
# $ref: "./access_token.yaml"
# csrfToken:
# $ref: "./xsrf_token_cookie.yaml"
XsrfAuthHeader:
type: apiKey
in: header
name: X-XSRF-TOKEN
description: |
Anti-CSRF token. Must match the `XSRF-TOKEN` cookie.
Required for all state-changing requests (POST/PUT/PATCH/DELETE).