From 9db3b41fdbd9f4e8486c7cb793a4a64ede94f91f Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Mon, 8 Jun 2026 20:52:02 +0200
Subject: [PATCH] docs(api): document reorder full-list contract in OpenAPI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add @Operation annotation to reorderItems() clarifying that itemIds must
contain ALL item IDs for the journey in the desired order — a partial list
returns 400 Bad Request. This surfaces the contract in the generated
OpenAPI spec and Swagger UI.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../familienarchiv/geschichte/GeschichteController.java       | 4 ++++
 1 file changed, 4 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 8113238c..b675a2b5 100644
--- a/backend/src/main/java/org/raddatz/familienarchiv/geschichte/GeschichteController.java
+++ b/backend/src/main/java/org/raddatz/familienarchiv/geschichte/GeschichteController.java
@@ -102,6 +102,10 @@ public class GeschichteController {
 
     @PutMapping("/{id}/items/reorder")
     @RequirePermission(Permission.BLOG_WRITE)
+    @Operation(
+        summary = "Reorder journey items",
+        description = "itemIds must contain ALL item IDs for the given journey in the desired new order. Sending a partial list returns 400 Bad Request."
+    )
     public List<JourneyItemView> reorderItems(
             @PathVariable UUID id,
             @RequestBody JourneyReorderDTO dto) {