Add search param documentation

Author: anderslindho

src/main/java/org/phoebus/channelfinder/CFResourceDescriptors.java

@@ -9,4 +9,12 @@ public class CFResourceDescriptors {
     public static final String CHANNEL_RESOURCE_URI = CF_SERVICE + "/resources/channels";
     public static final String SCROLL_RESOURCE_URI = CF_SERVICE + "/resources/scroll";
     public static final String CHANNEL_PROCESSOR_RESOURCE_URI = CF_SERVICE + "/resources/processors";
+
+    public static final String SEARCH_PARAM_DESCRIPTION = 
+        "Search parameters. Examples:\n" +
+        "- ~name: Filter by channel name (e.g., ~name=SR*)\n" +
+        "- ~tag: Filter by tag name, use ! to negate (e.g., ~tag=active)\n" +
+        "- ~size: Number of results (e.g., ~size=100)\n" +
+        "- ~from: Starting index (e.g., ~from=0)\n" +
+        "Use |,; as value separators";
 }

src/main/java/org/phoebus/channelfinder/ChannelManager.java

@@ -8,6 +8,7 @@
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import org.phoebus.channelfinder.AuthorizationService.ROLES;
 import org.phoebus.channelfinder.entity.Channel;
 import org.phoebus.channelfinder.entity.Property;
@@ -42,6 +43,7 @@
 import java.util.stream.StreamSupport;
 
 import static org.phoebus.channelfinder.CFResourceDescriptors.CHANNEL_RESOURCE_URI;
+import static org.phoebus.channelfinder.CFResourceDescriptors.SEARCH_PARAM_DESCRIPTION;
 
 @CrossOrigin
 @RestController
@@ -93,7 +95,9 @@ public class ChannelManager {
                             content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
             })
     @GetMapping
-    public List<Channel> query(@RequestParam MultiValueMap<String, String> allRequestParams) {
+    public List<Channel> query(
+            @Parameter(description = SEARCH_PARAM_DESCRIPTION)
+            @RequestParam MultiValueMap<String, String> allRequestParams) {
         return channelRepository.search(allRequestParams).channels();
     }
 
@@ -120,7 +124,9 @@ public List<Channel> query(@RequestParam MultiValueMap<String, String> allReques
                             content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
             })
     @GetMapping("/combined")
-    public SearchResult combinedQuery(@RequestParam MultiValueMap<String, String> allRequestParams) {
+    public SearchResult combinedQuery(
+            @Parameter(description = SEARCH_PARAM_DESCRIPTION)
+            @RequestParam MultiValueMap<String, String> allRequestParams) {
         return channelRepository.search(allRequestParams);
     }
 
@@ -142,7 +148,9 @@ public SearchResult combinedQuery(@RequestParam MultiValueMap<String, String> al
                             content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
             })
     @GetMapping("/count")
-    public long queryCount(@RequestParam MultiValueMap<String, String> allRequestParams) {
+    public long queryCount(
+            @Parameter(description = SEARCH_PARAM_DESCRIPTION)
+            @RequestParam MultiValueMap<String, String> allRequestParams) {
         return channelRepository.count(allRequestParams);
     }
 

src/main/java/org/phoebus/channelfinder/ChannelScroll.java

@@ -7,6 +7,7 @@
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import java.text.MessageFormat;
 import java.util.Comparator;
 import java.util.List;
@@ -73,7 +74,9 @@ public class ChannelScroll {
                             content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
             })
     @GetMapping
-    public Scroll query(@RequestParam MultiValueMap<String, String> allRequestParams) {
+    public Scroll query(
+            @Parameter(description = CFResourceDescriptors.SEARCH_PARAM_DESCRIPTION)
+            @RequestParam MultiValueMap<String, String> allRequestParams) {
         return search(null, allRequestParams);
     }
 
@@ -95,7 +98,10 @@ public Scroll query(@RequestParam MultiValueMap<String, String> allRequestParams
                             content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
             })
     @GetMapping("/{scrollId}")
-    public Scroll query(@PathVariable("scrollId") String scrollId, @RequestParam MultiValueMap<String, String> searchParameters) {
+    public Scroll query(
+            @Parameter(description = "Scroll ID from previous query") @PathVariable("scrollId") String scrollId,
+            @Parameter(description = CFResourceDescriptors.SEARCH_PARAM_DESCRIPTION)
+            @RequestParam MultiValueMap<String, String> searchParameters) {
         return search(scrollId, searchParameters);
     }
 

src/main/java/org/phoebus/channelfinder/processors/ChannelProcessorManager.java

@@ -6,6 +6,7 @@
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import org.phoebus.channelfinder.AuthorizationService;
 import org.phoebus.channelfinder.ChannelScroll;
 import org.phoebus.channelfinder.entity.Channel;
@@ -29,6 +30,7 @@
 import java.util.logging.Logger;
 
 import static org.phoebus.channelfinder.CFResourceDescriptors.CHANNEL_PROCESSOR_RESOURCE_URI;
+import static org.phoebus.channelfinder.CFResourceDescriptors.SEARCH_PARAM_DESCRIPTION;
 
 @RestController
 @RequestMapping(CHANNEL_PROCESSOR_RESOURCE_URI)
@@ -136,7 +138,9 @@ public long processAllChannels() {
                             content = @Content(schema = @Schema(implementation = Long.class)))
             })
     @PutMapping("/process/query")
-    public long processChannels(@RequestParam MultiValueMap<String, String> allRequestParams) {
+    public long processChannels(
+            @Parameter(description = SEARCH_PARAM_DESCRIPTION)
+            @RequestParam MultiValueMap<String, String> allRequestParams) {
         long channelCount = 0;
         Scroll scrollResult = channelScroll.query(allRequestParams);
         channelCount += scrollResult.getChannels().size();