Compare commits

...
4 Commits
Author SHA1 Message Date
Technoir 8e3c6b8c36 beispiele für Items und Kategorien hinzugefügt 2026-10-19 11:25:47 +02:00
Technoir 57c541bbb7 readme 2026-10-19 11:19:08 +02:00
Technoir d5389af958 api doc 2026-10-19 11:19:00 +02:00
Technoir ad4a9d12d5 fehlermeldungen zu deutsch geändert
da #29 nicht mehr erfüllt werden kann
2026-10-19 10:21:04 +02:00
8 changed files with 288 additions and 6 deletions

No files matched your search

+48
View File
@@ -0,0 +1,48 @@
# Einkaufsliste
Repository für das Webapp-Projekt, was eine Einkaufsliste zur Verfügung stellt.
Es ist möglich, mehrere Listen anzulegen. In einer Liste kann man Gegenstände und Kategorien erstellen. Gegenständen können, aber müssen nicht Kategorien gehören.
## Dokumentation
### Entwicklungsverlauf und User Stories
Dieses Projekt hat seine Dokumentation über Gitea vorgenommen. Die Entwicklungshistorie ist über die Commitliste einsehbar, User-Stories und andere Entwicklungsentscheidungen wurden über Issues abgewickelt. Es wurden auch Meilensteine verwendet um die Issues zu organisieren.
## Architektur
Die Seite verfolgt einen clientseitig gerenderter Ansatz. Das Backend schickt dem Browser eine HTML-Datei, welche in Teilen mit Attributen bei Custom Elementen und Daten befüllt sind. Der Client rendert dann die Custom Elemente.
Die Webseite selbst ist so ziemlich im Frontend benutzbar. Ein Neuladen der Seite ist nicht nötig, mit Ausnahme wenn man zwischen Listen und der Listenübersicht wechselt.
### Backend
Für das Backend wurde Spring mit Thymeleaf für das Bereitstellen von Seiten genutzt (`src/main/java/de/timaldinger/einkaufsliste`). Das Backend ist über eine RESTful-API ansprechbar. Die Datenbank ist H2.
### Frontend
Für das Frontend wurde Vanilla-JS und CSS benutzt.
## API Übersicht
| Pfad | Zugelassene Methoden | Angesprochene Modelle |
| ----------------- | ------------------------ | --------------------- |
| `/api/lists` | GET, POST, DELETE, PATCH | Einkaufslisten |
| `/api/categories` | GET, POST, DELETE, PATCH | Kategorien |
| `/api/items` | GET, POST, DELETE, PATCH | Gegenstände |
Die vollständige API-Dokumentation befindet sich unter `/docs/`.
## Aufsetzen
Auf der Maschine muss Java 25 und Maven installiert sein.
```
# Repo clonen
git clone https://gitea.von.timaldinger.de/Technoir/einkaufsliste-web.git
# Im Ordner
mvn spring-boot:run
```
Nun kann man im Browser `localhost:8080` aufrufen.
## Dokumentation
Weitere Dokumentation befindet sich unter `/docs/`
### Nutzung von KI
Es wurde Claude Code Opus 4.8 genutzt. Die KI wurde benutzt zum Debuggen bei scheinbar nicht erkennbaren Fehlern, großen Refactors und als Nachschlagwerk genutzt.
Konzept-, Architekturentscheidungen und Umsetzung des Projekts liegen an mir.
Vorschläge von KI wurden geprüft und bewusst übernommen oder verworfen.
+234
View File
@@ -0,0 +1,234 @@
# API
Die API versucht möglichst RESTful zu sein. Es hat:
- Ressourcen im Plural
- Client-Server Trennung, Änderung der Daten auf der Oberfläche geschieht über `fetch()` an die API
- Einheitliche Schnittstelle
Die Schnittstelle erfolgt vollständig über JSON.
Es wurde auf Cache-fähigkeit verzichtet aus Zeitgründen. HATEOAS ist auch nicht vorhanden, da Zeitgründe und fragwürdig, ob es für ein Projekt diesen Umfang nötig ist.
## API Pfade
IDs sind im UUID Format
### Listen `/api/lists`
| Pfad | Methoden | Beschreibung | Parameter | Codes Erfolg |
| ------------ | -------- | --------------------------------------------------- | ----------------------------------------- | ------------ |
| `/api/lists` | `GET` | Gibt alle vorhandenen Listen zurück mit Name und ID | / | 200 |
| | `POST` | Erlaubt es eine neue Liste zu erstellen | `listName` für den gewünschten Listenname | 201 |
#### `GET /api/lists` - Alle Listen
##### Body Beispiel
Leer
##### Response Beispiel
```json
[
{
"listName": "Liste 1",
"listID": "ddb3ac36-8213-4f9d-bf1e-39c836768e57"
},
{
"listName": "Liste 2",
"listID": "8937a2fa-2ab1-4b1e-8ee2-17bb0358dc1f"
},
...
]
```
#### `POST /api/lists` - Erstellen einer Liste
##### Body Beispiel
```json
{
"listName": "Listenname"
}
```
##### Response Beispiel
```json
{
"listName": "Listenname",
"listID": "ddb3ac36-8213-4f9d-bf1e-39c836768e57"
}
```
### Liste `/api/lists`
| Pfad | Methoden | Beschreibung | Parameter | Codes Erfolg |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------ |
| `/api/lists/{id}` | GET | Gibt alle Gegenstände und Kategorien (mit ihren Gegenständen) in der Liste mit der UUID id zurück | `id`: UUID der Liste in der URL | 200 |
| | PATCH | Verändert den Namen der Liste | `id`: UUID der Liste in der URL. Im Body `listName` für den neuen Namen | 204 |
| | DELETE | löscht eine Liste | `id`: UUID Der Liste in der URL | 204 |
#### GET `/api/lists/{id}` - Inhalt der Liste
##### Body Beispiel
/
##### Response Beispiel
```json
{
"categories": [
{
"categoryName": "testkategorie",
"items": [
{
"status": false,
"itemName": "test",
"itemAmount": "1",
"itemID": "99403d02-4771-4a5a-b6a7-6f3af0a5ee84",
"categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4",
"listID": "9038b8ef-7be8-4dcb-9229-6f51b11be137"
},
{
"status": true,
"itemName": "test",
"itemAmount": "2",
"itemID": "fc2806f6-d430-49f8-8c56-a6e2bc9792a7",
"categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4",
"listID": "9038b8ef-7be8-4dcb-9229-6f51b11be137"
}
],
"categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4"
}
],
"itemsNoCategory": [ //Gegenstände ohne Kategorie
{
"status": false,
"itemName": "test",
"itemAmount": "3",
"itemID": "38a0991e-4b51-42d7-b12c-0ddbcf6f583e",
"categoryID": null,
"listID": "9038b8ef-7be8-4dcb-9229-6f51b11be137"
}
]
}
```
#### `PATCH /api/lists/{id}` - Bearbeiten der Liste
##### Body
```json
{
"listName": "neuer Listname"
}
```
##### Response
/
#### `DELETE /api/lists/{id}` - Löschen einer Liste
##### Body
/
##### Response
/
### Kategorien `/api/categories`
| Pfad | Methoden | Beschreibung | Parameter | Codes Erfolg |
| ---------------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `/api/categories/{id}` | `GET` | Gibt den Inhalt der Kategorie zurück | / | 200 |
| | `POST` | Erlaubt es eine neue Kategorie zu erstellen | `categoryName` im Body für den gewünschten Kategorienamen | 201 |
| | `PATCH` | Ändern vom Namen der Liste | `categoryName` im Body für neuen Kategorienamen | 204 |
| | `DELETE` | Löschen einer Liste | `deleteAllItems=(true\|false)` als Queryparameter. Entscheidet, ob Gegenstände in der Kategorie mitgelöscht werden sollen | 204 |
#### `GET /api/categories/{id}` - Inhalt der Kategorie
##### Body Beispiel
/
##### Response Beispiel
```json
{
"categoryName": "testkategorie",
"items": [
{
"status": false,
"itemName": "test",
"itemAmount": "1",
"itemID": "99403d02-4771-4a5a-b6a7-6f3af0a5ee84",
"categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4",
"listID": "9038b8ef-7be8-4dcb-9229-6f51b11be137"
}
],
"categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4"
}
```
#### `POST /api/categories` - Erstellen einer Kategorie
##### Body Beispiel
```json
{
"categoryName": "testKategorie",
"listID": "9038b8ef-7be8-4dcb-9229-6f51b11be137"
}
```
##### Response Beispiel
```json
{
"categoryName": "testKategorie",
"categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4"
}
```
#### `PATCH /api/categories/{id}` - Bearbeiten der Kategorie
##### Body Beispiel
```json
{
"categoryName": "Gemüse"
}
```
##### Response
/
#### `DELETE /api/categories/{id}?deleteAllItems=(true|false)`
##### Body
/
##### Response
/
### Gegenstände `/api/items`
| Pfad | Methoden | Beschreibung | Parameter | Codes Erfolg |
| ----------------- | -------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `/api/items/{id}` | `GET` | Gibt den Inhalt des Gegenstands zurück | / | 200 |
| | `POST` | Erlaubt es einen neuen Gegenstand zu erstellen | `itemName,itemAmount,categoryID?,listID` im Body, für den Namen und Menge (entweder beide oder mindst einer muss vorhanden sein). | 201 |
| | `PATCH` | Ändern vom Namen, Menge oder Status eines Gegenstands | `itemName, itemAmount, isDone, categoryID` im Body. | 204 |
| | `DELETE` | Löschen eines Gegenstands | / | 204 |
#### `GET /api/items/{id}` - Inhalt des Gegenstands
##### Body Beispiel
/
##### Response Beispiel
```json
{
"status": false,
"itemName": "Milch",
"itemAmount": "1L",
"itemID": "38a0991e-4b51-42d7-b12c-0ddbcf6f583e",
"categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4",
"listID": "9038b8ef-7be8-4dcb-9229-6f51b11be137"
}
```
#### `POST /api/items` - Erstellen eines Gegenstands
##### Body Beispiel
```json
{
"itemName": "Milch",
"itemAmount": "1L",
"categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4",
"listID": "9038b8ef-7be8-4dcb-9229-6f51b11be137"
}
```
##### Response Beispiel
```json
{
"itemName": "Milch",
"itemAmount": "1L",
"itemID": "38a0991e-4b51-42d7-b12c-0ddbcf6f583e",
"categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4"
}
```
#### `PATCH /api/items/{id}` - Bearbeiten eines Gegenstands
##### Body Beispiel
```json
{
"isDone": true
}
```
##### Response
/
#### `DELETE /api/items/{id}` - Löschen eines Gegenstands
##### Body
/
##### Response
/
@@ -2,5 +2,5 @@ package de.timaldinger.einkaufsliste.Dto.Patch;
import jakarta.validation.constraints.NotBlank;
public record ShoppingCategoryPatchDTO(@NotBlank(message = "categoryName can't be blank") String categoryName) {
public record ShoppingCategoryPatchDTO(@NotBlank(message = "Kategoriename darf nicht leer sein!") String categoryName) {
}
@@ -6,7 +6,7 @@ import java.util.UUID;
public record ShoppingItemPatchDTO(String itemName, String itemAmount, Boolean isDone, UUID categoryID) {
@AssertTrue(message = "itemName and itemAmount both cant be blank!")
@AssertTrue(message = "Wenigstens eines der Felder muss ausgefüllt sein!")
private boolean isAtleastOneNotBlank(){
boolean n = itemName != null && !itemName.isBlank();
boolean a = itemAmount != null && !itemAmount.isBlank();
@@ -2,5 +2,5 @@ package de.timaldinger.einkaufsliste.Dto.Patch;
import jakarta.validation.constraints.NotBlank;
public record ShoppingListPatchDTO(@NotBlank(message = "listName must not be blank!") String listName) {
public record ShoppingListPatchDTO(@NotBlank(message = "Listenname darf nicht leer sein!") String listName) {
}
@@ -4,5 +4,5 @@ import jakarta.validation.constraints.NotBlank;
import java.util.UUID;
public record ShoppingCategoryPostDTO(@NotBlank(message = "categoryName must not be blank!") String categoryName, UUID listID) {
public record ShoppingCategoryPostDTO(@NotBlank(message = "Kategoriename darf nicht leer sein!") String categoryName, UUID listID) {
}
@@ -11,7 +11,7 @@ public record ShoppingItemPostDTO(String itemName,
@NotNull(message = "listID must not be empty!")
UUID listID){
@AssertTrue(message = "itemName and itemAmount cant both be blank!")
@AssertTrue(message = "Wenigstens eines der Felder muss ausgefüllt sein!")
private boolean isAtleastOneNotBlank(){
boolean n = itemName != null && !itemName.isBlank();
boolean a = itemAmount != null && !itemAmount.isBlank();
@@ -2,5 +2,5 @@ package de.timaldinger.einkaufsliste.Dto.Post;
import jakarta.validation.constraints.NotBlank;
public record ShoppingListPostDTO(@NotBlank(message = "listName must not be blank!") String listName) {
public record ShoppingListPostDTO(@NotBlank(message = "Listenname darf nicht leer sein!") String listName) {
}