From 56935b4331f011a5aee2ede99a54d5b5c07d0fed Mon Sep 17 00:00:00 2001 From: Marcel Date: Fri, 12 Jun 2026 07:42:27 +0200 Subject: [PATCH] docs(geschichte): annotate query parameters on GET /api/geschichten Adds @Parameter descriptions to status, personId, documentId, and limit on GeschichteController.list() so Swagger UI shows semantics including the permission-gated PUBLISHED override and DRAFT author-scoping for status, the AND-filter semantics for personId, and the default/cap for limit (refs #794). Co-Authored-By: Claude Sonnet 4.6 --- .../familienarchiv/geschichte/GeschichteController.java | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/backend/src/main/java/org/raddatz/familienarchiv/geschichte/GeschichteController.java b/backend/src/main/java/org/raddatz/familienarchiv/geschichte/GeschichteController.java index 30b6af59..604cc034 100644 --- a/backend/src/main/java/org/raddatz/familienarchiv/geschichte/GeschichteController.java +++ b/backend/src/main/java/org/raddatz/familienarchiv/geschichte/GeschichteController.java @@ -9,6 +9,7 @@ import org.raddatz.familienarchiv.geschichte.journeyitem.JourneyReorderDTO; import org.raddatz.familienarchiv.security.Permission; import org.raddatz.familienarchiv.security.RequirePermission; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.DeleteMapping; @@ -35,9 +36,13 @@ public class GeschichteController { @GetMapping public List list( + @Parameter(description = "Filter by status. Callers without BLOG_WRITE always receive PUBLISHED results regardless of the value passed. Callers with BLOG_WRITE requesting DRAFT receive only their own unpublished stories.") @RequestParam(required = false) GeschichteStatus status, + @Parameter(description = "AND-filter: story must include all supplied person IDs.") @RequestParam(name = "personId", required = false) List personIds, + @Parameter(description = "Filter to stories containing this document.") @RequestParam(required = false) UUID documentId, + @Parameter(description = "Maximum results to return. Values ≤ 0 default to 50. Clamped at 200.") @RequestParam(required = false, defaultValue = "50") int limit) { return geschichteService.list( status,