Rest API Swagger doc QA - coverages and coveragestores (#2525)

* Rest API Swagger doc QA - coverages and coveragestores

* Move filename parameter for upload to individual controller pathvariables for tranparency

* remove redundant format request param, retaining path mapping for gsconfig compatibility

* Swagger syntax improvements based on feedback

doc/en/api/1.0.0/coverages.yaml

@@ -116,7 +116,7 @@ paths:
         405:
           description: Method not allowed.
 
-  /workspaces/{workspace}/coveragestores/coverages:
+  /workspaces/{workspace}/coverages:
       get:
         operationId: getCoverageStore
         description: |
@@ -235,7 +235,7 @@ paths:
             type: string
           - name: quietOnNotFound
             in: query
-            description: The quietOnNotFound parameter avoids to log an Exception when the coverage is not present. Note that 404 status code will be returned anyway. Defaults to "false".
+            description: The quietOnNotFound parameter avoids to log an Exception when the coverage is not present. Note that 404 status code will be returned anyway.
             type: boolean
             required: false
             default: false
@@ -534,7 +534,7 @@ paths:
           type: string    
         - name: quietOnNotFound
           in: query
-          description: The quietOnNotFound parameter avoids to log an Exception when the coverage is not present. Note that 404 status code will be returned anyway. Defaults to "false".
+          description: The quietOnNotFound parameter avoids to log an Exception when the coverage is not present. Note that 404 status code will be returned anyway.
           type: boolean
           required: false
           default: false
@@ -823,12 +823,44 @@ paths:
           required: true
           schema:
             $ref: "#/definitions/CoverageInfo"
+        - name: calculate
+          in: query
+          description: Comma-seperated list of optional fields to calculate. Optional fields include: "nativebbox", "latlonbbox".
+          required: false
+          type: array
+          collectionFormat: csv
+          minItems: 0
+          maxItems: 2
+          items:
+            type: string
+            enum: [nativebbox,latlonbbox]
       responses:
         200:
           description: The coverage was successfully updated.
     delete:
       operationId: deleteWorkspaceCoverage
       description: Delete a coverage (optionally recursively deleting layers).
+      parameters:
+        - name: workspace
+          in: path
+          description: The name of the workspace
+          required: true
+          type: string
+        - name: store
+          in: path
+          description: The name of the coverage data store
+          required: true
+          type: string
+        - name: coverage
+          in: path
+          description: The name of the coverage
+          required: true
+          type: string
+        - name: recurse
+          in: query
+          required: false
+          description: The recurse controls recursive deletion. When set to true all stores containing the resource are also removed.
+          default: false
       responses:
         200:
           description: Successfully deleted.

doc/en/api/1.0.0/coveragestores.yaml

@@ -215,7 +215,7 @@ paths:
 
     delete:
       operationId: deleteCoverageStore
-      summary: Delete coveraeg store
+      summary: Delete coverage store
       description: Deletes a coverage store
       parameters:
         - name: workspace
@@ -288,7 +288,7 @@ paths:
         - name: filename
           in: query
           required: false
-          description: The filename parameter specifies the target file name for a file that needs to harvested as part of a mosaic. This is important to avoid clashes and to make sure the right dimension values are available in the name for multidimensional mosaics to work.
+          description: The filename parameter specifies the target file name for a file that needs to harvested as part of a mosaic. This is important to avoid clashes and to make sure the right dimension values are available in the name for multidimensional mosaics to work. Only used if method="file".
           type: string
       responses:
         200:
@@ -339,6 +339,11 @@ paths:
           required: false
           description: Name of the newly created coverage/layer. 
           type: string
+        - name: filename
+          in: query
+          required: false
+          description: The filename parameter specifies the target file name for a file that needs to harvested as part of a mosaic. This is important to avoid clashes and to make sure the right dimension values are available in the name for multidimensional mosaics to work. Only used if method="file".
+          type: string
       responses:
         200:
           description: The coverage store was successfully updated.

doc/en/api/1.0.0/structuredcoverages.yaml

@@ -177,6 +177,7 @@ paths:
           required: false
           type: integer
           minimum: 0
+          default: 0
         - name: limit
           in: query
           description: Used for paging, the number of items to be returned
@@ -384,19 +385,25 @@ paths:
           required: false
           description: A CQL filter to reduce the returned granules
           type: string
+        - name: offset
+          in: query
+          description: Used for paging, the start of the current page
+          required: false
+          type: integer
+          minimum: 0
+        - name: limit
+          in: query
+          description: Used for paging, the number of items to be removed
+          required: false
+          type: integer
+          minimum: 1
       responses:
         200:
           description: OK
         405:
           description: Method Not Allowed
 
   /workspaces/{workspace}/coveragestores/{store}/coverages/{coverage}/index/granules/{granuleId}:
-    parameters:
-      - name: granuleId
-        type: string
-        in: path
-        required: true
-        description: The granule ID
     get:
       operationId: getStructuredCoverageGranule
       summary: Get the attributes of a particular granule
@@ -419,7 +426,12 @@ paths:
           in: path
           required: true
           description: The name of the coverage to be retrieved
-          type: string       
+          type: string
+        - name: granuleId
+          type: string
+          in: path
+          required: true
+          description: The granule ID
       responses:
         200:
           description: OK
@@ -557,11 +569,16 @@ paths:
           required: true
           description: The name of the coverage to be retrieved
           type: string
+        - name: granuleId
+          type: string
+          in: path
+          required: true
+          description: The granule ID
       responses:
         200:
           description: OK
-        405:
-          description: Method Not Allowed
+        401:
+          description: Unauthorized
 
 
 definitions:

src/restconfig/src/main/java/org/geoserver/rest/catalog/AbstractStoreUploadController.java

@@ -53,7 +53,7 @@ public AbstractStoreUploadController(Catalog catalog) {
      * @param directory
      *
      */
-    protected List<Resource> handleFileUpload(String store, String workspace, UploadMethod method,
+    protected List<Resource> handleFileUpload(String store, String workspace, String filename, UploadMethod method,
             String format, Resource directory, HttpServletRequest request) {
 
         List<Resource> files = new ArrayList<>();
@@ -65,7 +65,6 @@ protected List<Resource> handleFileUpload(String store, String workspace, Upload
                 // we want to delete the previous dir contents only in case of PUT, not
                 // in case of POST (harvest, available only for raster data)
                 boolean cleanPreviousContents = HttpMethod.PUT.name().equals(request.getMethod());
-                String filename = request.getParameter("filename");
                 if (filename == null) {
                     filename = buildUploadedFilename(store, format);
                 }

src/restconfig/src/main/java/org/geoserver/rest/catalog/CoverageStoreController.java

@@ -124,7 +124,7 @@ public ResponseEntity<String> coverageStorePost(
             MediaTypeExtensions.TEXT_JSON_VALUE,
             MediaType.APPLICATION_XML_VALUE,
             MediaType.TEXT_XML_VALUE })
-    public void coverageStoreGet(
+    public void coverageStorePut(
             @RequestBody CoverageStoreInfo info,
             @PathVariable String workspaceName,
             @PathVariable String storeName) {

src/restconfig/src/main/java/org/geoserver/rest/catalog/CoverageStoreFileController.java

@@ -81,6 +81,7 @@ public void coverageStorePost(
             @PathVariable String storeName,
             @PathVariable UploadMethod method,
             @PathVariable String format,
+            @RequestParam(required = false) String filename,
             HttpServletRequest request) throws IOException {
 
         // check the coverage store exists
@@ -107,7 +108,7 @@ public void coverageStorePost(
         StructuredGridCoverage2DReader sr = (StructuredGridCoverage2DReader) reader;
         // This method returns a List of the harvested files.
         final List<File> uploadedFiles = new ArrayList<>();
-        for (Resource res : doFileUpload(method, workspaceName, storeName, format, request)) {
+        for (Resource res : doFileUpload(method, workspaceName, storeName, filename, format, request)) {
             uploadedFiles.add(Resources.find(res));
         }
         // File Harvesting
@@ -124,12 +125,13 @@ public RestWrapper<CoverageStoreInfo> coverageStorePut(
             @RequestParam(name = "configure", required = false) String configure,
             @RequestParam(name = "USE_JAI_IMAGEREAD", required = false) Boolean useJaiImageRead,
             @RequestParam(name = "coverageName", required = false) String coverageName,
+            @RequestParam(required = false) String filename,
             HttpServletRequest request) throws IOException {
 
         Format coverageFormat = getCoverageFormat(format);
 
         // doFileUpload returns a List of File but in the case of a Put operation the list contains only a value
-        List<Resource> files = doFileUpload(method, workspaceName, storeName, format, request);
+        List<Resource> files = doFileUpload(method, workspaceName, storeName, filename, format, request);
         final Resource uploadedFile = files.get(0);
 
         // create a builder to help build catalog objects
@@ -401,7 +403,7 @@ protected Resource findPrimaryFile(Resource directory, String format) {
      * @throws IOException
      */
     protected List<Resource> doFileUpload(UploadMethod method, String workspaceName,
-            String storeName, String format, HttpServletRequest request) throws IOException {
+            String storeName, String filename, String format, HttpServletRequest request) throws IOException {
         Resource directory = null;
 
         boolean postRequest = request != null
@@ -417,7 +419,7 @@ protected List<Resource> doFileUpload(UploadMethod method, String workspaceName,
                 directory = createFinalRoot(workspaceName, storeName, postRequest);
             }
         }
-        return handleFileUpload(storeName, workspaceName, method, format, directory, request);
+        return handleFileUpload(storeName, workspaceName, filename, method, format, directory, request);
     }
 
     private Resource createFinalRoot(String workspaceName, String storeName, boolean isPost)

src/restconfig/src/main/java/org/geoserver/rest/catalog/DataStoreFileController.java

@@ -222,12 +222,13 @@ public void dataStorePut(
             @RequestParam(name = "target", required = false) String target,
             @RequestParam(name = "update", required = false) String update,
             @RequestParam(name = "charset", required = false) String characterset,
+            @RequestParam(name = "filename", required = false) String filename,
             HttpServletRequest request, HttpServletResponse response) throws IOException {
 
         response.setStatus(HttpStatus.ACCEPTED.value());
 
         // doFileUpload returns a List of File but in the case of a Put operation the list contains only a value
-        List<Resource> files = doFileUpload(method, workspaceName, storeName, format, request);
+        List<Resource> files = doFileUpload(method, workspaceName, storeName, filename, format, request);
         final Resource uploadedFile = files.get(0);
 
         DataAccessFactory factory = lookupDataStoreFactory(format);
@@ -505,8 +506,8 @@ public void dataStorePut(
      * @param format The store format.
      * @throws IOException
      */
-    protected List<Resource> doFileUpload(UploadMethod method, String workspaceName,
-                                          String storeName, String format, HttpServletRequest request) throws IOException {
+    protected List<Resource> doFileUpload(UploadMethod method, String workspaceName, String storeName, String filename,
+                                          String format, HttpServletRequest request) throws IOException {
         Resource directory = null;
 
         boolean postRequest = request != null
@@ -522,7 +523,7 @@ protected List<Resource> doFileUpload(UploadMethod method, String workspaceName,
                 directory = createFinalRoot(workspaceName, storeName, postRequest);
             }
         }
-        return handleFileUpload(storeName, workspaceName, method, format, directory, request);
+        return handleFileUpload(storeName, workspaceName, filename, method, format, directory, request);
     }
 
     private Resource createFinalRoot(String workspaceName, String storeName, boolean isPost)

src/restconfig/src/main/java/org/geoserver/rest/catalog/StructuredCoverageController.java

@@ -196,15 +196,16 @@ private Filter getGranuleIdFilter(String granuleId) {
 
     /*
      * Note, the .+ regular expression allows granuleId to contain dots instead of having them
-     * interpreted as format extension
+     * interpreted as format extension.
+     * Note: the optional /{format} suffix is required for compatibility with gsconfig, but does not actually do
+     * anything otherwise.
      */
     @DeleteMapping(path = {"/granules/{granuleId:.+}", "/granules/{granuleId:.+}/{format}"})
     @ResponseBody
     public void granuleDelete(@PathVariable(name = "workspaceName") String workspaceName,
             @PathVariable String storeName,
             @PathVariable String coverageName,
-            @PathVariable String granuleId,
-            @PathVariable(name = "format", required = false) String gsConfigFormat) throws IOException {
+            @PathVariable String granuleId) throws IOException {
 
         // gsConfigForma allows for weird calls gsconfig does, like granules/granule.id/.json
         GranuleStore store = getGranuleStore(workspaceName, storeName, coverageName);