From 158501114386e5e5967877b1fe81e7c67820136f Mon Sep 17 00:00:00 2001 From: Teriuihi Date: Thu, 10 Apr 2025 22:46:30 +0200 Subject: [PATCH] Refactor API structure and endpoints for history and team. Updated API definitions and endpoints to better support punishment history and team queries. Introduced new parameters, schemas, and operations to improve functionality, and reorganized related controllers into appropriate packages. --- .../history/HistoryApiController.java | 21 ++ .../{ => team}/TeamApiController.java | 2 +- open_api/src/main/resources/api.yml | 18 +- .../src/main/resources/sub_api/bans/bans.yml | 182 ++++++++++++++---- .../src/main/resources/sub_api/team/team.yml | 55 +++--- 5 files changed, 201 insertions(+), 77 deletions(-) create mode 100644 backend/src/main/java/com/alttd/altitudeweb/controllers/history/HistoryApiController.java rename backend/src/main/java/com/alttd/altitudeweb/controllers/{ => team}/TeamApiController.java (97%) diff --git a/backend/src/main/java/com/alttd/altitudeweb/controllers/history/HistoryApiController.java b/backend/src/main/java/com/alttd/altitudeweb/controllers/history/HistoryApiController.java new file mode 100644 index 0000000..78a51d2 --- /dev/null +++ b/backend/src/main/java/com/alttd/altitudeweb/controllers/history/HistoryApiController.java @@ -0,0 +1,21 @@ +package com.alttd.altitudeweb.controllers.history; + +import com.alttd.altitudeweb.api.HistoryApi; +import org.springframework.http.ResponseEntity; + +public class HistoryApiController implements HistoryApi { + @Override + public ResponseEntity getHistoryForUsers(String userType, String type, String user) throws Exception { + return null; + } + + @Override + public ResponseEntity getHistoryForUuid(String userType, String type, String uuid) throws Exception { + return null; + } + + @Override + public ResponseEntity getUserNames(String userType, String type) throws Exception { + return null; + } +} diff --git a/backend/src/main/java/com/alttd/altitudeweb/controllers/TeamApiController.java b/backend/src/main/java/com/alttd/altitudeweb/controllers/team/TeamApiController.java similarity index 97% rename from backend/src/main/java/com/alttd/altitudeweb/controllers/TeamApiController.java rename to backend/src/main/java/com/alttd/altitudeweb/controllers/team/TeamApiController.java index 20d9820..43cf166 100644 --- a/backend/src/main/java/com/alttd/altitudeweb/controllers/TeamApiController.java +++ b/backend/src/main/java/com/alttd/altitudeweb/controllers/team/TeamApiController.java @@ -1,4 +1,4 @@ -package com.alttd.altitudeweb.controllers; +package com.alttd.altitudeweb.controllers.team; import com.alttd.altitudeweb.api.TeamApi; import com.alttd.altitudeweb.database.Connection; diff --git a/open_api/src/main/resources/api.yml b/open_api/src/main/resources/api.yml index 6d41d52..3df005f 100644 --- a/open_api/src/main/resources/api.yml +++ b/open_api/src/main/resources/api.yml @@ -7,10 +7,16 @@ info: servers: - url: https://alttd.com/api/v3 tags: - - name: player - description: Retrieve player information + - name: history + description: Retrieves punishment history + - name: team + description: Retrieves information about the staff team paths: - /team: - $ref: './sub_api/team/team.yml' - /history: - $ref: './sub_api/bans/bans.yml' + /team/{team}: + $ref: './sub_api/team/team.yml#/getTeam' + /history/{userType}/search/{type}: + $ref: './sub_api/bans/bans.yml#/getUserNames' + /history/{userType}/{type}/{user}: + $ref: './sub_api/bans/bans.yml#/getHistoryForUsers' + /history/{userType}/{type}/{uuid}: + $ref: './sub_api/bans/bans.yml#/getHistoryForUuid' diff --git a/open_api/src/main/resources/sub_api/bans/bans.yml b/open_api/src/main/resources/sub_api/bans/bans.yml index e4c75b6..fc83ce4 100644 --- a/open_api/src/main/resources/sub_api/bans/bans.yml +++ b/open_api/src/main/resources/sub_api/bans/bans.yml @@ -1,47 +1,145 @@ -paths: - /history: - post: - tags: - - user - summary: Get player history - description: Retrieves all types of player history about the player - operationId: getPlayerHistory - requestBody: - description: The player history - content: - application/json: - schema: - $ref: '#/components/schemas/Player' - responses: - '200': - description: successful operation - content: - application/json: - schema: - $ref: '#/components/schemas/PlayerHistory' - default: - description: Unexpected error - content: - application/json: - schema: - $ref: "../generic/errors.yml#/components/schemas/Error" +getUserNames: + post: + tags: + - history + summary: Get user names + description: Get all user names with punishment history of the specified type + operationId: getUserNames + parameters: + - $ref: '#/components/parameters/UserType' + - $ref: '#/components/parameters/HistoryType' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + type: array + items: + type: string + description: A list of users + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "../generic/errors.yml#/components/schemas/Error" +getHistoryForUsers: + post: + tags: + - history + summary: Get history for users + description: > + Get all users with punishment history of the specified type, + where the user name starts with the search query + operationId: getHistoryForUsers + parameters: + - $ref: '#/components/parameters/UserType' + - $ref: '#/components/parameters/HistoryType' + - $ref: '#/components/parameters/User' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/PunishmentHistory' + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "../generic/errors.yml#/components/schemas/Error" +getHistoryForUuid: + post: + tags: + - history + summary: Get user + description: > + Get all users with punishment history of the specified type, + where the user uuid matches + operationId: getHistoryForUuid + parameters: + - $ref: '#/components/parameters/UserType' + - $ref: '#/components/parameters/HistoryType' + - $ref: '#/components/parameters/Uuid' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/PunishmentHistory' + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "../generic/errors.yml#/components/schemas/Error" components: + parameters: + HistoryType: + name: type + in: path + required: true + schema: + type: string + enum: [ all, bans, mutes, kicks ] + description: The type of history to retrieve + User: + name: user + in: path + required: true + schema: + type: string + description: The (partial) username to search for + Uuid: + name: uuid + in: path + required: true + schema: + type: string + description: The uuid of the desired user + UserType: + name: userType + in: path + required: true + schema: + type: string + enum: [ player, staff ] + description: Indicates if this is a staff history or a player history look up schemas: - PlayerHistory: - type: object - properties: - punishmentType: - type: string - punishment: - type: string - active: - type: boolean - start: - type: integer - format: int64 - duration: - type: integer - format: int64 + PunishmentHistory: + type: array + items: + type: object + properties: + username: + type: string + description: The username of the user + uuid: + type: string + description: The UUID of the user + reason: + type: string + description: The reason for the punishment + type: + type: string + description: The type of punishment + punishmentTime: + type: integer + format: int64 + description: The time when the punishment was given + expiryTime: + type: integer + format: int64 + description: The time when the punishment expires + punishmentUser: + type: string + description: The username of the punishment issuer + punishmentUserUuid: + type: string + description: The UUID of the punishment issuer Player: type: object properties: diff --git a/open_api/src/main/resources/sub_api/team/team.yml b/open_api/src/main/resources/sub_api/team/team.yml index 0f67d93..c975c6f 100644 --- a/open_api/src/main/resources/sub_api/team/team.yml +++ b/open_api/src/main/resources/sub_api/team/team.yml @@ -1,31 +1,30 @@ -paths: - /{group}: - get: - tags: - - team - summary: Get team members - description: Retrieve players who are part of the specified team - operationId: getTeamMembers - parameters: - - name: group - in: path - required: true - description: The group name of the team - schema: - type: string - responses: - '200': - description: successful operation - content: - application/json: - schema: - $ref: '#/components/schemas/TeamMembers' - default: - description: Unexpected error - content: - application/json: - schema: - $ref: "../generic/errors.yml#/components/schemas/Error" +getTeam: + get: + tags: + - team + summary: Get team members + description: Retrieve players who are part of the specified team + operationId: getTeamMembers + parameters: + - name: group + in: path + required: true + description: The group name of the team + schema: + type: string + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/TeamMembers' + default: + description: Unexpected error + content: + application/json: + schema: + $ref: "../generic/errors.yml#/components/schemas/Error" components: schemas: TeamMembers: