basic schema definition

src/ApiDomain/Schema/External/Api/Health/request.json

@@ -0,0 +1,13 @@
+{
+  "get": {
+    "description": "Checks the health of the API backend",
+    "responses": {
+      "200": {
+        "$ref": "./response.json"
+      },
+      "default": {
+        "$ref": "../../../Partials/Response/bad-request.json"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Api/Health/response.json

@@ -0,0 +1,10 @@
+{
+  "description": "Successfully checked the health of the API backend",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "string"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Api/Schema/request.json

@@ -0,0 +1,13 @@
+{
+  "get": {
+    "description": "Reads the current schema definition",
+    "responses": {
+      "200": {
+        "$ref": "./response.json"
+      },
+      "default": {
+        "$ref": "../../../Partials/Response/bad-request.json"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Api/Schema/response.json

@@ -0,0 +1,16 @@
+{
+  "description": "Successfully read the schema definition",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "object",
+        "required": [
+          "openapi",
+          "info",
+          "paths",
+          "components"
+        ]
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Authentication/ConfirmRegistration/request.json

@@ -0,0 +1,44 @@
+{
+  "post": {
+    "description": "Confirms a registration and sets the initial password.",
+    "requestBody": {
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "required": [
+              "id",
+              "password",
+              "passwordConfirmation"
+            ],
+            "properties": {
+              "id": {
+                "$ref": "../../../Partials/uuid.json"
+              },
+              "password": {
+                "$ref": "../Partials/password.json"
+              },
+              "passwordConfirmation": {
+                "$ref": "../Partials/password.json"
+              }
+            }
+          }
+        }
+      }
+    },
+    "responses": {
+      "200": {
+        "$ref": "./response.json"
+      },
+      "401": {
+        "$ref": "../../../Partials/Response/unauthorized.json"
+      },
+      "403": {
+        "$ref": "../../../Partials/Response/forbidden.json"
+      },
+      "default": {
+        "$ref": "../../../Partials/Response/bad-request.json"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Authentication/ConfirmRegistration/response.json

@@ -0,0 +1,34 @@
+{
+  "description": "Successfully confirmed registration",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "object",
+        "required": [
+          "id",
+          "username",
+          "roleIdentifier",
+          "permissions"
+        ],
+        "properties": {
+          "id": {
+            "$ref": "../../../Partials/uuid.json"
+          },
+          "username": {
+            "$ref": "../Partials/username.json"
+          },
+          "roleIdentifier": {
+            "$ref": "../Partials/role-identifier.json"
+          },
+          "permissions": {
+            "description": "All permissions assigned to the user",
+            "type": "array",
+            "items":  {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Authentication/ForgotPassword/request.json

@@ -0,0 +1,36 @@
+{
+  "post": {
+    "description": "Requests a password reset mail, by providing a registered email address",
+    "requestBody": {
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "required": [
+              "mail"
+            ],
+            "properties": {
+              "mail": {
+                "$ref": "../Partials/mail.json"
+              }
+            }
+          }
+        }
+      }
+    },
+    "responses": {
+      "200": {
+        "$ref": "./response.json"
+      },
+      "401": {
+        "$ref": "../../../Partials/Response/unauthorized.json"
+      },
+      "403": {
+        "$ref": "../../../Partials/Response/forbidden.json"
+      },
+      "default": {
+        "$ref": "../../../Partials/Response/bad-request.json"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Authentication/ForgotPassword/response.json

@@ -0,0 +1,9 @@
+{
+  "description": "Password reset mail successfully sent",
+  "content": {
+    "application/json": {
+      "schema": {
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Authentication/Login/request.json

@@ -0,0 +1,40 @@
+{
+  "post": {
+    "description": "Login with user credentials.",
+    "requestBody": {
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "required": [
+              "identifier",
+              "password"
+            ],
+            "properties": {
+              "identifier": {
+                "$ref": "../Partials/identifier.json"
+              },
+              "password": {
+                "$ref": "../Partials/password.json"
+              }
+            }
+          }
+        }
+      }
+    },
+    "responses": {
+      "200": {
+        "$ref": "./response.json"
+      },
+      "401": {
+        "$ref": "../../../Partials/Response/unauthorized.json"
+      },
+      "403": {
+        "$ref": "../../../Partials/Response/forbidden.json"
+      },
+      "default": {
+        "$ref": "../../../Partials/Response/bad-request.json"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Authentication/Login/response.json

@@ -0,0 +1,18 @@
+{
+  "description": "User successfully logged in",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "object",
+        "required": [
+          "sessionId"
+        ],
+        "properties": {
+          "sessionId": {
+            "$ref": "../../../Partials/uuid.json"
+          }
+        }
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Authentication/Logout/request.json

@@ -0,0 +1,19 @@
+{
+  "get": {
+    "description": "Logout the currently logged in user.",
+    "responses": {
+      "200": {
+        "$ref": "./response.json"
+      },
+      "401": {
+        "$ref": "../../../Partials/Response/unauthorized.json"
+      },
+      "403": {
+        "$ref": "../../../Partials/Response/forbidden.json"
+      },
+      "default": {
+        "$ref": "../../../Partials/Response/bad-request.json"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Authentication/Logout/response.json

@@ -0,0 +1,10 @@
+{
+  "description": "User successfully logged out",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "string"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Authentication/Partials/identifier.json

@@ -0,0 +1,5 @@
+{
+  "description": "The identifier for the user. May be a mail address or a username",
+  "example": "max.mustermann@example.com",
+  "type": "string"
+}

src/ApiDomain/Schema/External/Authentication/Partials/mail.json

@@ -0,0 +1,6 @@
+{
+  "description": "The mail address of a user",
+  "example": "max.mustermann@example.com",
+  "type": "string",
+  "format": "email"
+}

src/ApiDomain/Schema/External/Authentication/Partials/password.json

@@ -0,0 +1,5 @@
+{
+  "description": "The password for an account",
+  "example": "Password123!",
+  "type": "string"
+}

src/ApiDomain/Schema/External/Authentication/Partials/role-identifier.json

@@ -0,0 +1,9 @@
+{
+  "description": "A role identifier",
+  "example": "admin",
+  "type": "string",
+  "enum": [
+    "admin",
+    "user"
+  ]
+}

src/ApiDomain/Schema/External/Authentication/Partials/username.json

@@ -0,0 +1,5 @@
+{
+  "description": "The username of a user",
+  "example": "max.mustermann",
+  "type": "string"
+}

src/ApiDomain/Schema/External/Authentication/RegisterUser/request.json

@@ -0,0 +1,40 @@
+{
+  "post": {
+    "description": "Creates a registration for a new user with their username and email address",
+    "requestBody": {
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "required": [
+              "username",
+              "mail"
+            ],
+            "properties": {
+              "username": {
+                "$ref": "../Partials/username.json"
+              },
+              "mail": {
+                "$ref": "../Partials/mail.json"
+              }
+            }
+          }
+        }
+      }
+    },
+    "responses": {
+      "200": {
+        "$ref": "./response.json"
+      },
+      "401": {
+        "$ref": "../../../Partials/Response/unauthorized.json"
+      },
+      "403": {
+        "$ref": "../../../Partials/Response/forbidden.json"
+      },
+      "default": {
+        "$ref": "../../../Partials/Response/bad-request.json"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Authentication/RegisterUser/response.json

@@ -0,0 +1,10 @@
+{
+  "description": "Successfully created the registration",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "string"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Authentication/ResetPassword/request.json

@@ -0,0 +1,44 @@
+{
+  "post": {
+    "description": "Sets a new Password by providing a password reset token and the new password",
+    "requestBody": {
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "required": [
+              "passwordToken",
+              "newPassword",
+              "passwordConfirmation"
+            ],
+            "properties": {
+              "passwordToken": {
+                "$ref": "../../../Partials/uuid.json"
+              },
+              "newPassword": {
+                "$ref": "../Partials/password.json"
+              },
+              "passwordConfirmation": {
+                "$ref": "../Partials/password.json"
+              }
+            }
+          }
+        }
+      }
+    },
+    "responses": {
+      "200": {
+        "$ref": "./response.json"
+      },
+      "401": {
+        "$ref": "../../../Partials/Response/unauthorized.json"
+      },
+      "403": {
+        "$ref": "../../../Partials/Response/forbidden.json"
+      },
+      "default": {
+        "$ref": "../../../Partials/Response/bad-request.json"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/Authentication/ResetPassword/response.json

@@ -0,0 +1,9 @@
+{
+  "description": "Successfully set new password",
+  "content": {
+    "application/json": {
+      "schema": {
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/User/ChangePassword/request.json

@@ -0,0 +1,40 @@
+{
+  "post": {
+    "description": "Changes the currently logged in users password",
+    "requestBody": {
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "required": [
+              "password",
+              "newPassword"
+            ],
+            "properties": {
+              "password": {
+                "$ref": "../../Authentication/Partials/password.json"
+              },
+              "newPassword": {
+                "$ref": "../../Authentication/Partials/password.json"
+              }
+            }
+          }
+        }
+      }
+    },
+    "responses": {
+      "200": {
+        "$ref": "./response.json"
+      },
+      "401": {
+        "$ref": "../../../Partials/Response/unauthorized.json"
+      },
+      "403": {
+        "$ref": "../../../Partials/Response/forbidden.json"
+      },
+      "default": {
+        "$ref": "../../../Partials/Response/bad-request.json"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/User/ChangePassword/response.json

@@ -0,0 +1,9 @@
+{
+  "description": "Successfully changed the password",
+  "content": {
+    "application/json": {
+      "schema": {
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/User/ChangeUsername/request.json

@@ -0,0 +1,40 @@
+{
+  "post": {
+    "description": "Changes the currently logged in users username",
+    "requestBody": {
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "required": [
+              "password",
+              "newUsername"
+            ],
+            "properties": {
+              "password": {
+                "$ref": "../../Authentication/Partials/password.json"
+              },
+              "newUsername": {
+                "$ref": "../../Authentication/Partials/username.json"
+              }
+            }
+          }
+        }
+      }
+    },
+    "responses": {
+      "200": {
+        "$ref": "./response.json"
+      },
+      "401": {
+        "$ref": "../../../Partials/Response/unauthorized.json"
+      },
+      "403": {
+        "$ref": "../../../Partials/Response/forbidden.json"
+      },
+      "default": {
+        "$ref": "../../../Partials/Response/bad-request.json"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/User/ChangeUsername/response.json

@@ -0,0 +1,9 @@
+{
+  "description": "Successfully changed the username",
+  "content": {
+    "application/json": {
+      "schema": {
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/User/Create/request.json

@@ -0,0 +1,44 @@
+{
+  "post": {
+    "description": "Creates a User",
+    "requestBody": {
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "required": [
+              "username",
+              "mail",
+              "password"
+            ],
+            "properties": {
+              "username": {
+                "$ref": "../../Authentication/Partials/username.json"
+              },
+              "mail": {
+                "$ref": "../../Authentication/Partials/mail.json"
+              },
+              "password": {
+                "$ref": "../../Authentication/Partials/password.json"
+              }
+            }
+          }
+        }
+      }
+    },
+    "responses": {
+      "200": {
+        "$ref": "./response.json"
+      },
+      "401": {
+        "$ref": "../../../Partials/Response/unauthorized.json"
+      },
+      "403": {
+        "$ref": "../../../Partials/Response/forbidden.json"
+      },
+      "default": {
+        "$ref": "../../../Partials/Response/bad-request.json"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/User/Create/response.json

@@ -0,0 +1,42 @@
+{
+  "description": "Successfully created the user",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "object",
+        "required": [
+          "id",
+          "username",
+          "role",
+          "permissions",
+          "createdAt",
+          "updatedAt"
+        ],
+        "properties": {
+          "id": {
+            "$ref": "../../../Partials/uuid.json"
+          },
+          "username": {
+            "$ref": "../../Authentication/Partials/username.json"
+          },
+          "role": {
+            "$ref": "../../Authentication/Partials/role-identifier.json"
+          },
+          "permissions": {
+            "description": "All permissions assigned to the user",
+            "type": "array",
+            "items":  {
+              "type": "string"
+            }
+          },
+          "createdAt": {
+            "$ref": "../../../Partials/date-time.json"
+          },
+          "updatedAt": {
+            "$ref": "../../../Partials/date-time.json"
+          }
+        }
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/User/ReadList/request.json

@@ -0,0 +1,44 @@
+{
+  "post": {
+    "description": "Reads a paginated list of users",
+    "requestBody": {
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "required": [
+              "page",
+              "perPage",
+              "query"
+            ],
+            "properties": {
+              "page": {
+                "$ref": "../../../Partials/pagination-page.json"
+              },
+              "perPage": {
+                "$ref": "../../../Partials/pagination-per-page.json"
+              },
+              "query": {
+                "$ref": "../../../Partials/pagination-query.json"
+              }
+            }
+          }
+        }
+      }
+    },
+    "responses": {
+      "200": {
+        "$ref": "./response.json"
+      },
+      "401": {
+        "$ref": "../../../Partials/Response/unauthorized.json"
+      },
+      "403": {
+        "$ref": "../../../Partials/Response/forbidden.json"
+      },
+      "default": {
+        "$ref": "../../../Partials/Response/bad-request.json"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/User/ReadList/response.json

@@ -0,0 +1,50 @@
+{
+  "description": "Successfully read a list of paginated users",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "object",
+        "required": [
+          "total",
+          "items"
+        ],
+        "properties": {
+          "total": {
+            "$ref": "../../../Partials/pagination-total.json"
+          },
+          "items": {
+            "description": "The resultset",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "id",
+                "role",
+                "username",
+                "mail",
+                "lastLoginAt"
+              ],
+              "properties": {
+                "id": {
+                  "$ref": "../../../Partials/uuid.json"
+                },
+                "role": {
+                  "$ref": "../../Authentication/Partials/role-identifier.json"
+                },
+                "username": {
+                  "$ref": "../../Authentication/Partials/username.json"
+                },
+                "mail": {
+                  "$ref": "../../Authentication/Partials/mail.json"
+                },
+                "lastLoginAt": {
+                  "$ref": "../../../Partials/nullable-date-time.json"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/User/UserState/request.json

@@ -0,0 +1,19 @@
+{
+  "get": {
+    "description": "Reads the state of the currently logged in user",
+    "responses": {
+      "200": {
+        "$ref": "./response.json"
+      },
+      "401": {
+        "$ref": "../../../Partials/Response/unauthorized.json"
+      },
+      "403": {
+        "$ref": "../../../Partials/Response/forbidden.json"
+      },
+      "default": {
+        "$ref": "../../../Partials/Response/bad-request.json"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/External/User/UserState/response.json

@@ -0,0 +1,46 @@
+{
+  "description": "Successfully read the currently logged in users state",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "object",
+        "required": [
+          "id",
+          "username",
+          "roleIdentifier",
+          "permissions",
+          "createdAt",
+          "updatedAt",
+          "sessionId"
+        ],
+        "properties": {
+          "id": {
+            "$ref": "../../../Partials/uuid.json"
+          },
+          "username": {
+            "$ref": "../../Authentication/Partials/username.json"
+          },
+          "role": {
+            "$ref": "../../Authentication/Partials/role-identifier.json"
+          },
+          "permissions": {
+            "description": "All permissions assigned to the user",
+            "type": "array",
+            "items":  {
+              "type": "string"
+            }
+          },
+          "createdAt": {
+            "$ref": "../../../Partials/date-time.json"
+          },
+          "updatedAt": {
+            "$ref": "../../../Partials/date-time.json"
+          },
+          "sessionId": {
+            "$ref": "../../../Partials/uuid.json"
+          }
+        }
+      }
+    }
+  }
+}

src/ApiDomain/Schema/Partials/Response/bad-request.json

@@ -0,0 +1,32 @@
+{
+  "description": "Bad Request",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "object",
+        "required": [
+          "error"
+        ],
+        "properties": {
+          "error": {
+            "description": "The error response object",
+            "type": "object",
+            "required": [
+              "code"
+            ],
+            "properties": {
+              "code": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "example": {
+          "error": {
+            "code": "Username.AlreadyExists"
+          }
+        }
+      }
+    }
+  }
+}

src/ApiDomain/Schema/Partials/Response/forbidden.json

@@ -0,0 +1,10 @@
+{
+  "description": "The user is forbidden to perform this action",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "string"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/Partials/Response/success.json

@@ -0,0 +1,10 @@
+{
+  "description": "Success",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "string"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/Partials/Response/unauthorized.json

@@ -0,0 +1,10 @@
+{
+  "description": "Invalid credentials or invalid user session",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "string"
+      }
+    }
+  }
+}

src/ApiDomain/Schema/Partials/date-time.json

@@ -0,0 +1,6 @@
+{
+  "description": "A string representing a timestamp",
+  "example": "2024-11-10T21:24:04+00:00",
+  "type": "string",
+  "format": "date-time"
+}

src/ApiDomain/Schema/Partials/nullable-date-time.json

@@ -0,0 +1,7 @@
+{
+  "description": "A nullable string representing a timestamp",
+  "nullable": true,
+  "example": "2024-11-10T21:24:04+00:00",
+  "type": "string",
+  "format": "date-time"
+}

src/ApiDomain/Schema/Partials/nullable-time.json

@@ -0,0 +1,7 @@
+{
+  "description": "A nullable string indicating the time of day in a 24h format (HH:MM)",
+  "nullable": true,
+  "example": "04:20",
+  "type": "string",
+  "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$"
+}

src/ApiDomain/Schema/Partials/pagination-page.json

@@ -0,0 +1,6 @@
+{
+  "description": "The current page of a paginated list",
+  "type": "integer",
+  "example": 6,
+  "minimum": 1
+}

src/ApiDomain/Schema/Partials/pagination-per-page.json

@@ -0,0 +1,6 @@
+{
+  "description": "The maximum amount of items displayed on a page of a paginated list",
+  "type": "integer",
+  "example": 4,
+  "minimum": 1
+}

src/ApiDomain/Schema/Partials/pagination-query.json

@@ -0,0 +1,6 @@
+{
+  "description": "The nullable query to search for in a paginated list",
+  "example": "Growbox",
+  "type": "string",
+  "nullable": true
+}

src/ApiDomain/Schema/Partials/pagination-total.json

@@ -0,0 +1,6 @@
+{
+  "description": "The total amount of elements in a paginated list",
+  "type": "integer",
+  "example": 3,
+  "minimum": 0
+}

src/ApiDomain/Schema/Partials/time.json

@@ -0,0 +1,6 @@
+{
+  "description": "A string indicating the time of day in a 24h format (HH:MM)",
+  "example": "04:20",
+  "type": "string",
+  "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$"
+}

src/ApiDomain/Schema/Partials/uuid.json

@@ -0,0 +1,6 @@
+{
+  "description": "A universally unique identifier",
+  "example": "071ac920-38dc-11ed-a009-0242ac130005",
+  "format": "uuid",
+  "type": "string"
+}

src/ApiDomain/Schema/api.schema.json

@@ -0,0 +1,60 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Template API",
+    "description": "The API powering the Template application",
+    "version": "1.0.0"
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuth": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-API-Key"
+      }
+    }
+  },
+  "paths": {
+    "/api/health": {
+      "$ref": "External/Api/Health/request.json"
+    },
+    "/api/schema": {
+      "$ref": "External/Api/Schema/request.json"
+    },
+
+    "/api/auth/login-user": {
+      "$ref": "External/Authentication/Login/request.json"
+    },
+    "/api/auth/logout-user": {
+      "$ref": "External/Authentication/Logout/request.json"
+    },
+    "/api/auth/confirm-registration": {
+      "$ref": "External/Authentication/ConfirmRegistration/request.json"
+    },
+    "/api/auth/register-user": {
+      "$ref": "External/Authentication/RegisterUser/request.json"
+    },
+    "/api/auth/forgot-password": {
+      "$ref": "External/Authentication/ForgotPassword/request.json"
+    },
+    "/api/auth/reset-password": {
+      "$ref": "External/Authentication/ResetPassword/request.json"
+    },
+
+    "/api/user/create": {
+      "$ref": "External/User/Create/request.json"
+    },
+    "/api/user/change-password": {
+      "$ref": "External/User/ChangePassword/request.json"
+    },
+    "/api/user/change-username": {
+      "$ref": "External/User/ChangeUsername/request.json"
+    },
+    "/api/user/read-list": {
+      "$ref": "External/User/ReadList/request.json"
+    },
+    "/api/user/state": {
+      "$ref": "External/User/UserState/request.json"
+    }
+  }
+}