From 75abbb0a2a32551f3564a7995c6e54593b7222cf Mon Sep 17 00:00:00 2001
From: zihluwang <real@zihluwang.me>
Date: Mon, 13 Apr 2026 14:38:50 +0800
Subject: [PATCH] feat: add Swagger annotations for Firearm, Modification, and
 Tag controllers

---
 .../deltaforceguide/controller/FirearmController.java      | 7 ++++++-
 .../deltaforceguide/controller/ModificationController.java | 7 ++++++-
 .../onixbyte/deltaforceguide/controller/TagController.java | 4 ++++
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/src/main/java/com/onixbyte/deltaforceguide/controller/FirearmController.java b/src/main/java/com/onixbyte/deltaforceguide/controller/FirearmController.java
index f4d7a36..d6e8ca7 100644
--- a/src/main/java/com/onixbyte/deltaforceguide/controller/FirearmController.java
+++ b/src/main/java/com/onixbyte/deltaforceguide/controller/FirearmController.java
@@ -4,6 +4,8 @@ import com.onixbyte.deltaforceguide.domain.dto.FirearmResponse;
 import com.onixbyte.deltaforceguide.domain.dto.PageResponse;
 import com.onixbyte.deltaforceguide.enumeration.FirearmType;
 import com.onixbyte.deltaforceguide.service.FirearmService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.constraints.Max;
 import jakarta.validation.constraints.Min;
 import org.springframework.data.domain.PageRequest;
@@ -15,7 +17,7 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
-@Validated
+@Tag(name = "武器管理", description = "与武器有关的操作")
 @RestController
 @RequestMapping("/firearms")
 public class FirearmController {
@@ -26,6 +28,8 @@ public class FirearmController {
         this.firearmService = firearmService;
     }
 
+    @Operation(description = "获取分页武器数据")
+    @Validated
     @GetMapping
     public PageResponse<FirearmResponse> pageQuery(
             @RequestParam(defaultValue = "0") @Min(0) int page,
@@ -37,6 +41,7 @@ public class FirearmController {
         return firearmService.pageQuery(type, PageRequest.of(page, size, Sort.by(direction, sortBy)));
     }
 
+    @Operation(description = "获取指定武器的数据")
     @GetMapping("/{id}")
     public FirearmResponse queryById(@PathVariable Long id) {
         return firearmService.queryById(id);
diff --git a/src/main/java/com/onixbyte/deltaforceguide/controller/ModificationController.java b/src/main/java/com/onixbyte/deltaforceguide/controller/ModificationController.java
index 816adda..5f3b1c6 100644
--- a/src/main/java/com/onixbyte/deltaforceguide/controller/ModificationController.java
+++ b/src/main/java/com/onixbyte/deltaforceguide/controller/ModificationController.java
@@ -3,6 +3,8 @@ package com.onixbyte.deltaforceguide.controller;
 import com.onixbyte.deltaforceguide.domain.dto.ModificationResponse;
 import com.onixbyte.deltaforceguide.domain.dto.PageResponse;
 import com.onixbyte.deltaforceguide.service.ModificationService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.constraints.Max;
 import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.Positive;
@@ -17,7 +19,7 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
-@Validated
+@Tag(name = "改装管理", description = "对枪械改装的管理")
 @RestController
 @RequestMapping("/modifications")
 public class ModificationController {
@@ -28,6 +30,8 @@ public class ModificationController {
         this.modificationService = modificationService;
     }
 
+    @Operation(description = "分页查询改装信息")
+    @Validated
     @GetMapping
     public PageResponse<ModificationResponse> pageQuery(
             @RequestParam(defaultValue = "0") @Min(0) int page,
@@ -40,6 +44,7 @@ public class ModificationController {
         return modificationService.pageQuery(firearmId, tags, PageRequest.of(page, size, Sort.by(direction, sortBy)));
     }
 
+    @Operation(description = "查询指定改装的信息")
     @GetMapping("/{id}")
     public ModificationResponse queryById(@PathVariable Long id) {
         return modificationService.queryById(id);
diff --git a/src/main/java/com/onixbyte/deltaforceguide/controller/TagController.java b/src/main/java/com/onixbyte/deltaforceguide/controller/TagController.java
index 41230aa..e22097d 100644
--- a/src/main/java/com/onixbyte/deltaforceguide/controller/TagController.java
+++ b/src/main/java/com/onixbyte/deltaforceguide/controller/TagController.java
@@ -1,5 +1,7 @@
 package com.onixbyte.deltaforceguide.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
@@ -8,6 +10,7 @@ import com.onixbyte.deltaforceguide.service.ModificationService;
 
 import java.util.List;
 
+@Tag(name = "标签管理", description = "管理标签信息")
 @RestController
 @RequestMapping("/tags")
 public class TagController {
@@ -18,6 +21,7 @@ public class TagController {
         this.modificationService = modificationService;
     }
 
+    @Operation(description = "查询指定武器或所有武器的标签")
     @GetMapping
     public List<String> getTags(@RequestParam(required = false) Long firearmId) {
         return modificationService.findAllTags(firearmId);