Add @operation annotations for major endpoints

anderslindho · anderslindho · commit 93cd86f16075 · 2025-06-04T14:17:00.000+02:00
diff --git a/src/main/java/org/phoebus/channelfinder/ChannelManager.java b/src/main/java/org/phoebus/channelfinder/ChannelManager.java
@@ -7,6 +7,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 org.phoebus.channelfinder.AuthorizationService.ROLES;
 import org.phoebus.channelfinder.entity.Channel;
 import org.phoebus.channelfinder.entity.Property;
@@ -77,6 +78,12 @@ public class ChannelManager {
      * @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(
@@ -106,6 +113,12 @@ public List<Channel> query(@RequestParam MultiValueMap<String, String> allReques
      * @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(
@@ -134,6 +147,12 @@ public SearchResult combinedQuery(@RequestParam MultiValueMap<String, String> al
      * @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(
@@ -157,6 +176,12 @@ public long queryCount(@RequestParam MultiValueMap<String, String> allRequestPar
      * @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(
@@ -191,6 +216,12 @@ public Channel read(@PathVariable("channelName") String channelName) {
      * @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(
@@ -254,6 +285,12 @@ public Channel create(@PathVariable("channelName") String channelName, @RequestB
      * @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(
@@ -355,6 +392,12 @@ private void resetOwnersToExisting(Iterable<Channel> channels) {
      * @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(
@@ -434,6 +477,12 @@ public Channel update(@PathVariable("channelName") String channelName, @RequestB
      * @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(
@@ -503,6 +552,12 @@ public Iterable<Channel> update(@RequestBody Iterable<Channel> channels) {
      *
      * @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(
diff --git a/src/main/java/org/phoebus/channelfinder/ChannelScroll.java b/src/main/java/org/phoebus/channelfinder/ChannelScroll.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.text.MessageFormat;
 import java.util.Comparator;
 import java.util.List;
@@ -62,6 +63,12 @@ public class ChannelScroll {
      * @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(
@@ -86,6 +93,12 @@ public Scroll query(@RequestParam MultiValueMap<String, String> allRequestParams
      * @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(
diff --git a/src/main/java/org/phoebus/channelfinder/InfoManager.java b/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;
@@ -45,6 +46,12 @@ public class InfoManager {
      * 
      * @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(
diff --git a/src/main/java/org/phoebus/channelfinder/PropertyManager.java b/src/main/java/org/phoebus/channelfinder/PropertyManager.java
@@ -7,6 +7,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.text.MessageFormat;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -64,6 +65,12 @@ public class PropertyManager {
      *
      * @return list of all properties
      */
+    @Operation(
+        summary = "List all properties",
+        description = "Retrieve the list of all properties in the database.",
+        operationId = "listProperties",
+        tags = {"Property"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -91,6 +98,12 @@ public Iterable<Property> list() {
      * @param withChannels - get the channels with the property
      * @return found property
      */
+    @Operation(
+        summary = "Get property by name",
+        description = "Retrieve a property by its name. Optionally include its channels.",
+        operationId = "getPropertyByName",
+        tags = {"Property"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -134,6 +147,12 @@ public Property read(@PathVariable("propertyName") String propertyName,
      * @param property - an Property instance with the list of channels to add the property <code>propertyName</code> to
      * @return the created property
      */
+    @Operation(
+        summary = "Create or update a property",
+        description = "Create and exclusively update the property identified by the path parameter.",
+        operationId = "createOrUpdateProperty",
+        tags = {"Property"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -203,6 +222,12 @@ public Property create(@PathVariable("propertyName") String propertyName, @Reque
      * @param properties - XmlProperties to be created
      * @return the list of properties created
      */
+    @Operation(
+        summary = "Create multiple properties",
+        description = "Create multiple properties in a single request.",
+        operationId = "createMultipleProperties",
+        tags = {"Property"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -279,6 +304,12 @@ public Iterable<Property> create(@RequestBody Iterable<Property> properties) {
      * @param property - property payload with value
      * @return added property
      */
+    @Operation(
+        summary = "Add property to a single channel",
+        description = "Add the property identified by propertyName to the channel identified by channelName.",
+        operationId = "addPropertyToChannel",
+        tags = {"Property"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -353,6 +384,12 @@ public Property addSingle(@PathVariable("propertyName") String propertyName, @Pa
      * @param property - a Property instance with the list of channels to add the property <code>propertyName</code> to
      * @return the updated property
      */
+    @Operation(
+        summary = "Update a property",
+        description = "Update the property identified by the path parameter, adding it to all channels in the payload.",
+        operationId = "updateProperty",
+        tags = {"Property"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -473,6 +510,12 @@ public Property update(@PathVariable("propertyName") String propertyName, @Reque
      * @param properties - XmlProperties to be updated
      * @return the updated properties
      */
+    @Operation(
+        summary = "Update multiple properties",
+        description = "Update multiple properties and all appropriate channels.",
+        operationId = "updateMultipleProperties",
+        tags = {"Property"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -584,6 +627,12 @@ private void checkPropertyAuthorization(Optional<Property> existingProperty) {
      *
      * @param propertyName - name of property to remove
      */
+    @Operation(
+        summary = "Delete a property",
+        description = "Delete the property identified by the path parameter from all channels.",
+        operationId = "deleteProperty",
+        tags = {"Property"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
@@ -636,6 +685,12 @@ public void remove(@PathVariable("propertyName") String propertyName) {
      * @param propertyName - name of property to remove
      * @param channelName - channel to remove <code>propertyName</code> from
      */
+    @Operation(
+        summary = "Delete property from a channel",
+        description = "Delete the property identified by propertyName from the channel identified by channelName.",
+        operationId = "deletePropertyFromChannel",
+        tags = {"Property"}
+    )
     @ApiResponses(
             value = {
                     @ApiResponse(
diff --git a/src/main/java/org/phoebus/channelfinder/TagManager.java b/src/main/java/org/phoebus/channelfinder/TagManager.java
diff --git a/src/main/java/org/phoebus/channelfinder/processors/ChannelProcessorManager.java b/src/main/java/org/phoebus/channelfinder/processors/ChannelProcessorManager.java
