Merge pull request #183 from anderslindho/master

Improve swagger documentation with operation annotations

Author: jacomago

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

@@ -7,6 +7,8 @@
 import io.swagger.v3.oas.annotations.media.Schema;
 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;
@@ -41,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
@@ -69,14 +72,12 @@ public class ChannelManager {
     @Autowired
     ChannelProcessorService channelProcessorService;
 
-    /**
-     * GET method for querying a collection of Channel instances, based on a
-     * multi-parameter query specifying patterns for tags, property values, and
-     * channel names to match against.
-     * 
-     * @param allRequestParams query parameters
-     * @return list of all channels
-     */
+    @Operation(
+        summary = "Query channels",
+        description = "Query a collection of Channel instances based on tags, property values, and channel names.",
+        operationId = "queryChannels",
+        tags = {"Channel"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -94,18 +95,18 @@ 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();
     }
 
-    /**
-     * GET method for querying for a collection of Channel instances, based on a
-     * multi-parameter query specifying patterns for tags, property values, and
-     * channel names to match against.
-     *
-     * @param allRequestParams query parameters
-     * @return SearchResult a count to the total number of matches and the first 10k hits
-     */
+    @Operation(
+        summary = "Combined query for channels",
+        description = "Query for a collection of Channel instances and get a count and the first 10k hits.",
+        operationId = "combinedQueryChannels",
+        tags = {"Channel"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -123,17 +124,18 @@ 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);
     }
 
-    /**
-     * GET method for querying the number of matches to a multi-parameter query specifying patterns for tags, property values, and
-     * channel names to match against.
-     *
-     * @param allRequestParams query parameters
-     * @return a total number of channels that match the query parameters
-     */
+    @Operation(
+        summary = "Count channels matching query",
+        description = "Get the number of channels matching the given query parameters.",
+        operationId = "countChannels",
+        tags = {"Channel"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -146,17 +148,18 @@ 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);
     }
 
-    /**
-     * GET method for retrieving an instance of Channel identified by
-     * <code>channelName</code>.
-     *
-     * @param channelName - channel name to search for
-     * @return found channel
-     */
+    @Operation(
+        summary = "Get channel by name",
+        description = "Retrieve a Channel instance by its name.",
+        operationId = "getChannelByName",
+        tags = {"Channel"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -182,15 +185,12 @@ public Channel read(@PathVariable("channelName") String channelName) {
         }
     }
 
-    /**
-     * PUT method for creating/replacing a channel instance identified by the
-     * payload. The <b>complete</b> set of properties for the channel must be
-     * supplied, which will replace the existing set of properties.
-     *
-     * @param channelName - name of channel to be created 
-     * @param channel - new data (properties/tags) for channel <code>chan</code>
-     * @return the created channel
-     */
+    @Operation(
+        summary = "Create or replace a channel",
+        description = "Create or replace a channel instance identified by the payload.",
+        operationId = "createOrReplaceChannel",
+        tags = {"Channel"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -248,12 +248,12 @@ public Channel create(@PathVariable("channelName") String channelName, @RequestB
         }
     }
 
-    /**
-     * PUT method for creating multiple channels.
-     *
-     * @param channels - XmlChannels to be created
-     * @return the list of channels created
-     */
+    @Operation(
+        summary = "Create or replace multiple channels",
+        description = "Create or replace multiple channel instances.",
+        operationId = "createOrReplaceChannels",
+        tags = {"Channel"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -347,14 +347,12 @@ private void resetOwnersToExisting(Iterable<Channel> channels) {
         }
     }
 
-    /**
-     * POST method for merging properties and tags of the channel identified by the
-     * payload into an existing channel.
-     *
-     * @param channelName - name of channel to add
-     * @param channel - new Channel data (properties/tags) to be merged into channel <code>channelName</code>
-     * @return the updated channel         
-     */
+    @Operation(
+        summary = "Update a channel",
+        description = "Merge properties and tags of the channel identified by the payload into an existing channel.",
+        operationId = "updateChannel",
+        tags = {"Channel"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -427,13 +425,12 @@ public Channel update(@PathVariable("channelName") String channelName, @RequestB
         }
     }
 
-    /**
-     * POST method for merging properties and tags of the Channels identified by the
-     * payload into existing channels.
-     *
-     * @param channels - XmlChannels to be updated
-     * @return the updated channels
-     */
+    @Operation(
+        summary = "Update multiple channels",
+        description = "Merge properties and tags of the channels identified by the payload into existing channels.",
+        operationId = "updateChannels",
+        tags = {"Channel"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -497,12 +494,12 @@ public Iterable<Channel> update(@RequestBody Iterable<Channel> channels) {
         }
     }
 
-    /**
-     * DELETE method for deleting a channel instance identified by path parameter
-     * <code>channelName</code>.
-     *
-     * @param channelName - name of channel to remove
-     */
+    @Operation(
+        summary = "Delete a channel",
+        description = "Delete a channel instance identified by its name.",
+        operationId = "deleteChannel",
+        tags = {"Channel"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(

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

@@ -6,6 +6,8 @@
 import io.swagger.v3.oas.annotations.media.Schema;
 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;
@@ -54,14 +56,12 @@ public class ChannelScroll {
     @Qualifier("indexClient")
     ElasticsearchClient client;
 
-    /**
-     * GET method for retrieving a collection of Channel instances, based on a
-     * multi-parameter query specifying patterns for tags, property values, and
-     * channel names to match against.
-     *
-     * @param allRequestParams search parameters
-     * @return list of all channels
-     */
+    @Operation(
+        summary = "Scroll query for channels",
+        description = "Retrieve a collection of Channel instances based on multi-parameter search.",
+        operationId = "scrollQueryChannels",
+        tags = {"ChannelScroll"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -74,18 +74,18 @@ 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);
     }
 
-    /**
-     * GET method for retrieving a collection of Channel instances, based on a
-     * multi-parameter query specifying patterns for tags, property values, and
-     * channel names to match against.
-     *
-     * @param scrollId scroll Id
-     * @return list of all channels
-     */
+    @Operation(
+        summary = "Scroll query by scrollId",
+        description = "Retrieve a collection of Channel instances using a scrollId and search parameters.",
+        operationId = "scrollQueryById",
+        tags = {"ChannelScroll"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -98,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/InfoManager.java

@@ -6,6 +6,7 @@
 import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.Operation;
 import java.io.IOException;
 import java.util.LinkedHashMap;
 import java.util.Map;
@@ -41,10 +42,12 @@ public class InfoManager {
 
     private static final ObjectMapper objectMapper = new ObjectMapper().enable(SerializationFeature.INDENT_OUTPUT);
 
-    /**
-     * 
-     * @return Information about the ChannelFinder service
-     */
+    @Operation(
+        summary = "Get ChannelFinder service info",
+        description = "Returns information about the ChannelFinder service and its Elasticsearch backend.",
+        operationId = "getServiceInfo",
+        tags = {"Info"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(