From 539c6412a7e0522d7a922f5b88dbc7b9ae4e95d2 Mon Sep 17 00:00:00 2001 From: Sebastiaan de Schaetzen Date: Wed, 7 May 2025 18:54:36 +0200 Subject: [PATCH] Add OpenAPI spec --- .gitignore | 1 + common/api.yaml | 425 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 426 insertions(+) create mode 100644 .gitignore create mode 100644 common/api.yaml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..485dee6 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.idea diff --git a/common/api.yaml b/common/api.yaml new file mode 100644 index 0000000..ca5f294 --- /dev/null +++ b/common/api.yaml @@ -0,0 +1,425 @@ +openapi: 3.1.0 +info: + title: Allowance Planner + version: 1.0.0 +servers: + - url: 'https://allowance_planner.seeseepuff.be/v1' + description: 'API server' + - url: 'http://localhost/v1' + description: 'Local server' +paths: + + /users: + get: + summary: Gets all users + responses: + 200: + description: Information about every user + content: + application/json: + schema: + type: array + items: + type: object + properties: + id: + type: integer + description: The user ID + name: + type: string + description: The user name + + /user/{userId}: + get: + summary: Gets information about a user + parameters: + - in: path + name: userId + description: The user ID + required: true + schema: + type: integer + responses: + 200: + description: Information about the user + content: + application/json: + schema: + type: object + properties: + id: + type: integer + description: The user ID + name: + type: string + description: The user name + 404: + description: The users could not be found. + + /user/{userId}/allowance: + get: + summary: Gets the allowance breakdown of a user + parameters: + - in: path + name: userId + description: The user ID + required: true + schema: + type: integer + responses: + 200: + description: Information about the allowance of the user + content: + application/json: + schema: + type: object + properties: + allowance: + type: integer + description: The total allowance value of the user, in cents. + goals: + type: array + $ref: "#/components/schemas/goal" + post: + summary: Updates the allowance of a user + parameters: + - in: path + name: userId + description: The user ID + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + amount: + type: integer + description: The amount to update the allowance by, in cents. + description: + type: string + description: The description of the allowance or expense. + + /user/{userId}/history: + get: + summary: Gets the allowance history of a user + parameters: + - in: path + name: userId + description: The user ID + required: true + schema: + type: integer + responses: + 200: + description: Information about the allowance history of the user + content: + application/json: + schema: + type: array + items: + type: object + properties: + date: + type: string + format: date-time + description: The date of the allowance or expense. + amount: + type: integer + description: The amount of the allowance to be added, in cents. A negative value + + /user/{userId}/goals: + get: + summary: Gets all goals + parameters: + - in: path + name: userId + description: The user ID + required: true + schema: + type: integer + responses: + 200: + description: Information about the goals of the user + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/goal" + post: + summary: Creates a new goal + parameters: + - in: path + name: userId + description: The user ID + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The goal name. The goal with the name "null" is a special goal that represents the basic allowance functionality. + target: + type: integer + description: The target value of the goal, in cents + weight: + type: integer + description: How much money goes to this goal, relative to all other goals. + put: + summary: Bulk updating of goals + parameters: + - in: path + name: userId + description: The user ID + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: array + items: + type: object + properties: + id: + type: integer + description: The goal ID + weight: + type: integer + description: How much money goes to this goal, relative to all other goals. + + /user/{userId/goal/{goalId}: + get: + summary: Gets information about a goal + parameters: + - in: path + name: userId + description: The user ID + required: true + schema: + type: integer + - in: path + name: goalId + description: The goal ID + required: true + schema: + type: integer + responses: + 200: + description: Information about the goal + content: + application/json: + schema: + $ref: "#/components/schemas/goal" + 404: + description: The goal could not be found. + put: + summary: Updates a goal + parameters: + - in: path + name: userId + description: The user ID + required: true + schema: + type: integer + - in: path + name: goalId + description: The goal ID + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The new name of the goal, if set. + target: + type: integer + description: The target value of the goal, in cents, if set. + weight: + type: integer + description: How much money goes to this goal, relative to all other goals, if set. + responses: + 200: + description: The goal was updated successfully. + 404: + description: The goal could not be found. + + delete: + summary: Deletes a goal + parameters: + - in: path + name: userId + description: The user ID + required: true + schema: + type: integer + - in: path + name: goalId + description: The goal ID + required: true + schema: + type: integer + responses: + 200: + description: The goal was deleted successfully. + 404: + description: The goal could not be found. + + /user/{userId}/goal/{goalId}/complete: + post: + summary: Completes a goal. + description: Completes a goal. This will subtract this goal's value from the user's allowance and then remove the goal. + parameters: + - in: path + name: userId + description: The user ID + required: true + schema: + type: integer + - in: path + name: goalId + description: The goal ID + required: true + schema: + type: integer + + /tasks: + get: + summary: Gets all tasks + responses: + 200: + description: Information about every task + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/task" + post: + summary: Create a new task + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The task name + reward: + type: integer + description: The task reward, in cents + assigned: + type: integer + description: The user ID of the user assigned to the task + + /task/{id}: + get: + summary: Gets information about a task + parameters: + - in: path + name: id + description: The task ID + required: true + schema: + type: integer + - in: query + name: sort + description: The sort order of the tasks + required: false + schema: + type: enum + enum: + - reward + - recent + - old + responses: + 200: + description: Information about the task + content: + application/json: + schema: + $ref: "#/components/schemas/task" + 404: + description: The tasks could not be found. + put: + summary: Updates a task + parameters: + - in: path + name: id + description: The task ID + required: true + schema: + type: integer + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The task name + reward: + type: integer + description: The task reward, in cents + assigned: + type: integer + description: The user ID of the user assigned to the task + +components: + schemas: + task: + type: object + properties: + id: + type: integer + description: The task ID + name: + type: string + description: The task name + reward: + type: integer + description: The task reward, in cents + assigned: + type: integer + description: The user ID of the user assigned to the task + + goal: + type: object + properties: + id: + type: integer + description: The goal ID + name: + type: string + description: The goal name. The goal with the name "null" is a special goal that represents the basic allowance functionality. + target: + type: integer + description: The target value of the goal, in cents + progress: + type: integer + description: The progress of the goal, in cents + weight: + type: integer + description: How much money goes to this goal, relative to all other goals.