dcache-frontend: add more detailed description of request objects for…

… bulk and stage

Motivation:

Tier 1 (KIT) requested we include more description of
the request structure for the TAPE API Stage request
in the Swagger page.

Modification:

Add description to Stage, but also to the generic
Bulk request.

Result:

Happier users?

Target: master
Request: 8.2
Patch: https://rb.dcache.org/r/13917/
Requires-notes: yes
Acked-by: Dmitry

modules/dcache-frontend/src/main/java/org/dcache/restful/resources/bulk/BulkResources.java

@@ -208,12 +208,16 @@ public List<BulkRequestSummary> getRequests(
     @Consumes({MediaType.APPLICATION_JSON})
     @Produces(MediaType.APPLICATION_JSON)
     public Response submit(
-          @ApiParam(value = "Description of the request, which defines the following: "
-                + "target (list), target_prefix, activity, cancel_on_failure, "
-                + "clear_on_success, clear_on_failure, delay_clear, expand_directories "
-                + "(NONE, TARGETS, ALL), pre_store (store all targets first), "
-                + "and arguments (map of name:value "
-                + "pairs) if required.", required = true)
+          @ApiParam(value = "Description of the request, which defines the following:\n\n"
+                + "**target** - Array of file paths.  Required.\n"
+                + "**target_prefix** - String path prefix, applied to all targets. Optional.\n"
+                + "**activity** - String, name of the activity (PIN, UNPIN, DELETE, UPDATE_QOS). Required.\n"
+                + "**cancel_on_failure** - Boolean. Optional, defaults to false.\n"
+                + "**clear_on_success** - Boolean, Optional, defaults to false.\n"
+                + "**clear_on_failure** - Boolean, Optional, defaults to false.\n"
+                + "**expand_directories** - String (NONE, TARGETS, ALL). Optional, defaults to NONE\n"
+                + "**pre_store** - Boolean (store all targets first, including recursively discovered paths).  Optional, defaults to false.\n"
+                + "**arguments** - Object (map) of name:value pairs. Optional, specific to activity.", required = true)
                 String requestPayload) {
         Subject subject = getSubject();
         Restriction restriction = getRestriction();

modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/ArchiveInfoResources.java

@@ -126,7 +126,7 @@ public final class ArchiveInfoResources {
     @Consumes({MediaType.APPLICATION_JSON})
     @Produces(MediaType.APPLICATION_JSON)
     public List<ArchiveInfo> getArchiveInfo(
-          @ApiParam(value = "List of paths for which to return archive info (file locality).",
+          @ApiParam(value = "Array of paths for which to return archive info (file locality).",
                 required = true)
                 String requestPayload) {
 

modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/ReleaseResources.java

@@ -133,7 +133,7 @@ public final class ReleaseResources {
     @Produces(MediaType.APPLICATION_JSON)
     public Response release(
           @PathParam("id") String id,
-          @ApiParam(value = "List of file paths to release. If any path does not belong to the "
+          @ApiParam(value = "Array of file paths to release. If any path does not belong to the "
                 + "stage request corresponding to the id, this request will fail.", required = true)
                 String requestPayload) {
 

modules/dcache-frontend/src/main/java/org/dcache/restful/resources/tape/StageResources.java

@@ -249,10 +249,16 @@ public Response cancel(
     @Consumes({MediaType.APPLICATION_JSON})
     @Produces(MediaType.APPLICATION_JSON)
     public Response submit(
-          @ApiParam(value = "Description of the request, which consists of a list of file objects "
-                + "containing path, optional diskLifetime, and targetedMetadata. The latter is keyed "
-                + "to the sitename-from-well-known, and contains a map/object with site "
-                + "and implementation-specific attributes.", required = true)
+          @ApiParam(value = "Request structure:\n\n"
+                + "**files** - Array of File objects.  Required.\n"
+                + "File object structure:\n"
+                + "**path**:  - String.  Path of the file.  Duplicates will be sanitized.  Required.\n"
+                + "**diskLifetime**: - String of ISO 8601 format.  Duration after which the replica is considered no longer needed."
+                + "  Optional (defaults to system default for pin lifetime).\n"
+                + "**targetdMetadata** - targeted metadata object. Keyed to the sitename-from-well-known, "
+                + "and contains a map/object with site and implementation-specific attributes. "
+                + "Currently ignored by dCache.\n"
+                + "See further https://docs.google.com/document/d/1Zx_H5dRkQRfju3xIYZ2WgjKoOvmLtsafP2pKGpHqcfY/edit#heading=h.93yzfvog73oc.", required = true)
                 String requestPayload) {
         Subject subject = getSubject();
         Restriction restriction = getRestriction();