From 2025bb451fbde55c50f235117674aaea1ba751ee Mon Sep 17 00:00:00 2001 From: Iron_Felix Date: Wed, 19 Nov 2025 03:14:41 +0300 Subject: [PATCH] refact: openapi splitted into separate files --- api/openapi.yaml | 441 +------------------------ api/parameters/_index.yaml | 4 + api/parameters/cursor.yaml | 5 + api/parameters/title_sort.yaml | 5 + api/paths/titles-id.yaml | 29 ++ api/paths/titles.yaml | 73 ++++ api/paths/users-id-titles.yaml | 61 ++++ api/paths/users-id.yaml | 26 ++ api/schemas/CursorObj.yaml | 9 + api/schemas/Image.yaml | 9 + api/schemas/Review.yaml | 2 + api/schemas/Studio.yaml | 14 + api/schemas/Tag.yaml | 8 + api/schemas/Tags.yaml | 11 + api/schemas/Title.yaml | 63 ++++ api/schemas/TitleSort.yaml | 8 + api/schemas/User.yaml | 40 +++ api/schemas/UserTitle.yaml | 24 ++ api/schemas/_index.yaml | 26 ++ api/schemas/enums/ReleaseSeason.yaml | 7 + api/schemas/enums/TitleStatus.yaml | 6 + api/schemas/enums/UserTitleStatus.yaml | 7 + 22 files changed, 443 insertions(+), 435 deletions(-) create mode 100644 api/parameters/_index.yaml create mode 100644 api/parameters/cursor.yaml create mode 100644 api/parameters/title_sort.yaml create mode 100644 api/paths/titles-id.yaml create mode 100644 api/paths/titles.yaml create mode 100644 api/paths/users-id-titles.yaml create mode 100644 api/paths/users-id.yaml create mode 100644 api/schemas/CursorObj.yaml create mode 100644 api/schemas/Image.yaml create mode 100644 api/schemas/Review.yaml create mode 100644 api/schemas/Studio.yaml create mode 100644 api/schemas/Tag.yaml create mode 100644 api/schemas/Tags.yaml create mode 100644 api/schemas/Title.yaml create mode 100644 api/schemas/TitleSort.yaml create mode 100644 api/schemas/User.yaml create mode 100644 api/schemas/UserTitle.yaml create mode 100644 api/schemas/_index.yaml create mode 100644 api/schemas/enums/ReleaseSeason.yaml create mode 100644 api/schemas/enums/TitleStatus.yaml create mode 100644 api/schemas/enums/UserTitleStatus.yaml diff --git a/api/openapi.yaml b/api/openapi.yaml index b52ba58..281fe82 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -8,444 +8,15 @@ servers: 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: - $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 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 - + $ref: "./paths/titles.yaml" /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 - + $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 - + $ref: "./paths/users-id.yaml" /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 - + $ref: "./paths/users-id-titles.yaml" 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' - + $ref: "./parameters/_index.yaml" 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 - 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) - 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 + $ref: "./schemas/_index.yaml" diff --git a/api/parameters/_index.yaml b/api/parameters/_index.yaml new file mode 100644 index 0000000..6249e7d --- /dev/null +++ b/api/parameters/_index.yaml @@ -0,0 +1,4 @@ +cursor: + $ref: "./cursor.yaml" +title_sort: + $ref: "./title_sort.yaml" \ No newline at end of file diff --git a/api/parameters/cursor.yaml b/api/parameters/cursor.yaml new file mode 100644 index 0000000..1730f18 --- /dev/null +++ b/api/parameters/cursor.yaml @@ -0,0 +1,5 @@ +in: query +name: cursor +required: false +schema: + type: string diff --git a/api/parameters/title_sort.yaml b/api/parameters/title_sort.yaml new file mode 100644 index 0000000..615294b --- /dev/null +++ b/api/parameters/title_sort.yaml @@ -0,0 +1,5 @@ +in: query +name: sort +required: false +schema: + $ref: '../schemas/TitleSort.yaml' diff --git a/api/paths/titles-id.yaml b/api/paths/titles-id.yaml new file mode 100644 index 0000000..01fa504 --- /dev/null +++ b/api/paths/titles-id.yaml @@ -0,0 +1,29 @@ +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: "../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 diff --git a/api/paths/titles.yaml b/api/paths/titles.yaml new file mode 100644 index 0000000..4fd010d --- /dev/null +++ b/api/paths/titles.yaml @@ -0,0 +1,73 @@ +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: word + schema: + type: string + - in: query + name: status + schema: + $ref: '../schemas/enums/TitleStatus.yaml' + - 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 diff --git a/api/paths/users-id-titles.yaml b/api/paths/users-id-titles.yaml new file mode 100644 index 0000000..0cde5af --- /dev/null +++ b/api/paths/users-id-titles.yaml @@ -0,0 +1,61 @@ +get: + summary: Get user titles + parameters: + - $ref: '../parameters/cursor.yaml' + - in: path + name: user_id + required: true + schema: + type: string + - in: query + name: word + schema: + type: string + - in: query + name: status + schema: + $ref: '../schemas/enums/TitleStatus.yaml' + - in: query + name: watch_status + schema: + $ref: '../schemas/enums/UserTitleStatus.yaml' + - 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: fields + schema: + type: string + default: all + responses: + '200': + description: List of user titles + content: + application/json: + schema: + type: array + items: + $ref: '../schemas/UserTitle.yaml' + '204': + description: No titles found + '400': + description: Request params are not correct + '500': + description: Unknown server error diff --git a/api/paths/users-id.yaml b/api/paths/users-id.yaml new file mode 100644 index 0000000..0acdb81 --- /dev/null +++ b/api/paths/users-id.yaml @@ -0,0 +1,26 @@ +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: '../schemas/User.yaml' + '404': + description: User not found + '400': + description: Request params are not correct + '500': + description: Unknown server error diff --git a/api/schemas/CursorObj.yaml b/api/schemas/CursorObj.yaml new file mode 100644 index 0000000..5a3c96c --- /dev/null +++ b/api/schemas/CursorObj.yaml @@ -0,0 +1,9 @@ +type: object +required: + - id +properties: + id: + type: integer + format: int64 + param: + type: string diff --git a/api/schemas/Image.yaml b/api/schemas/Image.yaml new file mode 100644 index 0000000..7226b29 --- /dev/null +++ b/api/schemas/Image.yaml @@ -0,0 +1,9 @@ +type: object +properties: + id: + type: integer + format: int64 + storage_type: + type: string + image_path: + type: string diff --git a/api/schemas/Review.yaml b/api/schemas/Review.yaml new file mode 100644 index 0000000..a116dde --- /dev/null +++ b/api/schemas/Review.yaml @@ -0,0 +1,2 @@ +type: object +additionalProperties: true diff --git a/api/schemas/Studio.yaml b/api/schemas/Studio.yaml new file mode 100644 index 0000000..35b40a8 --- /dev/null +++ b/api/schemas/Studio.yaml @@ -0,0 +1,14 @@ +type: object +required: + - id + - name +properties: + id: + type: integer + format: int64 + name: + type: string + poster: + $ref: ./Image.yaml + description: + type: string diff --git a/api/schemas/Tag.yaml b/api/schemas/Tag.yaml new file mode 100644 index 0000000..7239b10 --- /dev/null +++ b/api/schemas/Tag.yaml @@ -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: 少女 diff --git a/api/schemas/Tags.yaml b/api/schemas/Tags.yaml new file mode 100644 index 0000000..ca8c4fd --- /dev/null +++ b/api/schemas/Tags.yaml @@ -0,0 +1,11 @@ +type: array +description: Array of localized tags +items: + $ref: ./Tag.yaml +example: +- en: Shojo + ru: Сёдзё + ja: 少女 +- en: Shounen + ru: Сёнен + ja: 少年 diff --git a/api/schemas/Title.yaml b/api/schemas/Title.yaml new file mode 100644 index 0000000..7497d1f --- /dev/null +++ b/api/schemas/Title.yaml @@ -0,0 +1,63 @@ +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 +additionalProperties: true diff --git a/api/schemas/TitleSort.yaml b/api/schemas/TitleSort.yaml new file mode 100644 index 0000000..d8ce8f7 --- /dev/null +++ b/api/schemas/TitleSort.yaml @@ -0,0 +1,8 @@ +type: string +description: Title sort order +default: id +enum: + - id + - year + - rating + - views diff --git a/api/schemas/User.yaml b/api/schemas/User.yaml new file mode 100644 index 0000000..8b4d88d --- /dev/null +++ b/api/schemas/User.yaml @@ -0,0 +1,40 @@ +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) + 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 diff --git a/api/schemas/UserTitle.yaml b/api/schemas/UserTitle.yaml new file mode 100644 index 0000000..658e350 --- /dev/null +++ b/api/schemas/UserTitle.yaml @@ -0,0 +1,24 @@ +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 +additionalProperties: true diff --git a/api/schemas/_index.yaml b/api/schemas/_index.yaml new file mode 100644 index 0000000..ac49f37 --- /dev/null +++ b/api/schemas/_index.yaml @@ -0,0 +1,26 @@ +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" diff --git a/api/schemas/enums/ReleaseSeason.yaml b/api/schemas/enums/ReleaseSeason.yaml new file mode 100644 index 0000000..5cf988d --- /dev/null +++ b/api/schemas/enums/ReleaseSeason.yaml @@ -0,0 +1,7 @@ +type: string +description: Title release season +enum: + - winter + - spring + - summer + - fall diff --git a/api/schemas/enums/TitleStatus.yaml b/api/schemas/enums/TitleStatus.yaml new file mode 100644 index 0000000..0bfce7d --- /dev/null +++ b/api/schemas/enums/TitleStatus.yaml @@ -0,0 +1,6 @@ +type: string +description: Title status +enum: + - finished + - ongoing + - planned diff --git a/api/schemas/enums/UserTitleStatus.yaml b/api/schemas/enums/UserTitleStatus.yaml new file mode 100644 index 0000000..0b1a90d --- /dev/null +++ b/api/schemas/enums/UserTitleStatus.yaml @@ -0,0 +1,7 @@ +type: string +description: User's title status +enum: + - finished + - planned + - dropped + - in-progress