Rest API Swagger doc QA - importer

geoserver · Oct 5, 2017 · e9edc94 · e9edc94
1 parent a07699b
commit e9edc94
Show file tree

Hide file tree

Showing 7 changed files with 72 additions and 34 deletions.
diff --git a/doc/en/api/1.0.0/importer.yaml b/doc/en/api/1.0.0/importer.yaml
@@ -14,7 +14,7 @@ paths:
         - application/json
         - text/html
       parameters:
-        - $ref: "#/parameters/ExpandParameter"
+        - $ref: "#/parameters/ExpandParameterNone"
       responses:
         200:
           description: OK
@@ -149,11 +149,20 @@ parameters:
     in: query
     type: boolean
     required: false
+  #This parameter is handled at the converter level, and applies to all endpoints which return content. Default is 1 (self), unless otherwise specified in the controller method.
   ExpandParameter:
     name: expand
     type: string
     in: query
-    description: 'What level to expand the response object to. Can be "self" (expand only the response object and its immediate children), "all" (expand all children), "none" (don''t include any children), or a nonnegative integer, indicating the depth of children to expand to. Defaults to "self" or "none", depending on the request.'
+    description: 'What level to expand the response object to. Can be "self" (expand only the response object and its immediate children), "all" (expand all children), "none" (don''t include any children), or a nonnegative integer, indicating the depth of children to expand to.'
+    default: self
+    required: false
+  ExpandParameterNone:
+    name: expand
+    type: string
+    in: query
+    description: 'What level to expand the response object to. Can be "self" (expand only the response object and its immediate children), "all" (expand all children), "none" (don''t include any children), or a nonnegative integer, indicating the depth of children to expand to.'
+    default: none
     required: false
   ContextParameter:
     name: importBody

diff --git a/doc/en/api/1.0.0/importerData.yaml b/doc/en/api/1.0.0/importerData.yaml
@@ -73,7 +73,7 @@ paths:
       operationId: deleteImportDataFile
       summary: Remove a specific file with id {filename} from the import with id {importId}. Only applies to file/directory imports.
       responses: 
-        202: 
+        204: 
           description: No Content
   /imports/{importId}/tasks/{taskId}/data/files:
     get:
@@ -112,15 +112,16 @@ paths:
       operationId: deleteTaskDataFile
       summary: Remove a specific file with id {filename} from the task with id {taskId} within import with id {importId}. Only applies to file/directory imports.
       responses: 
-        202: 
+        204: 
           description: No Content
 
 parameters:
   ExpandParameter:
     name: expand
     type: string
     in: query
-    description: 'What level to expand the response object to. Can be "self" (expand only the response object and its immediate children), "all" (expand all children), "none" (don''t include any children), or a nonnegative integer, indicating the depth of children to expand to. Defaults to "self" or "none", depending on the request.'
+    description: 'What level to expand the response object to. Can be "self" (expand only the response object and its immediate children), "all" (expand all children), "none" (don''t include any children), or a nonnegative integer, indicating the depth of children to expand to.'
+    default: self
     required: false
   ImportId:
     name: importId

diff --git a/doc/en/api/1.0.0/importerTasks.yaml b/doc/en/api/1.0.0/importerTasks.yaml
@@ -15,7 +15,7 @@ paths:
         - text/html
       parameters:
         - $ref: "#/parameters/ImportId"
-        - $ref: "#/parameters/ExpandParameter"
+        - $ref: "#/parameters/ExpandParameterNone"
       responses:
         200:
           description: OK
@@ -46,7 +46,8 @@ paths:
         - application/json
         - text/htm
       parameters:
-        - $ref: "#/parameters/ExpandParameter"
+        - $ref: "#/parameters/ImportId"
+        - $ref: "#/parameters/ExpandParameterNone"
         - $ref: "#/parameters/TaskParameter"
       responses:
         201:
@@ -121,12 +122,18 @@ paths:
         - $ref: "#/parameters/ImportId"      
         - $ref: "#/parameters/TaskId"
         - $ref: "#/parameters/TaskParameter"
+        - $ref: "#/parameters/ExpandParameter"
       responses:
         200: 
           description: OK
+          schema:
+            $ref: "#/definitions/Task"
     delete:
       operationId: deleteTask
       summary: Remove task with id {taskId} within import with id {importId}
+      parameters:
+        - $ref: "#/parameters/ImportId"      
+        - $ref: "#/parameters/TaskId"
       responses:
         200: 
           description: OK
@@ -141,6 +148,13 @@ paths:
         - $ref: "#/parameters/ImportId"
         - $ref: "#/parameters/Filename"        
         - $ref: "#/parameters/ExpandParameter"
+        - name: fileBody
+          in: body
+          required: true
+          description: The file contents to upload.
+          schema:
+            type: string
+            format: binary
       responses:
         201:
           description: Created
@@ -183,9 +197,6 @@ paths:
       consumes:
         - application/json
         - text/json
-      produces:
-        - application/json
-        - text/html
       parameters:
         - $ref: "#/parameters/ImportId"      
         - $ref: "#/parameters/TaskId"
@@ -234,8 +245,14 @@ parameters:
     name: expand
     type: string
     in: query
-    description: 'What level to expand the response object to. Can be "self" (expand only the response object and its immediate children), "all" (expand all children), "none" (don''t include any children), or a nonnegative integer, indicating the depth of children to expand to. Defaults to "self" or "none", depending on the request.'
+    description: 'What level to expand the response object to. Can be "self" (expand only the response object and its immediate children), "all" (expand all children), "none" (don''t include any children), or a nonnegative integer, indicating the depth of children to expand to.'
-    required: false
+    default: self
+  ExpandParameterNone:
+    name: expand
+    type: string
+    in: query
+    description: 'What level to expand the response object to. Can be "self" (expand only the response object and its immediate children), "all" (expand all children), "none" (don''t include any children), or a nonnegative integer, indicating the depth of children to expand to.'
+    default: none
   ImportId:
     name: importId
     in: path
@@ -267,14 +284,14 @@ parameters:
     in: body
     required: true          
     schema:
-      $ref: "#/definitions/Task"
+      $ref: "#/definitions/Store"
   LayerParameter:
     name: layerBody
     description: The layer to modify
     in: body
     required: true          
     schema:
-      $ref: "#/definitions/Task"
+      $ref: "#/definitions/Layer"
 
 definitions:
   Progress:

diff --git a/doc/en/api/1.0.0/importerTransforms.yaml b/doc/en/api/1.0.0/importerTransforms.yaml
@@ -2,8 +2,8 @@
 swagger: '2.0'
 info:
   version: 1.0.0
-  title: GeoServer Importer Extension - Main
+  title: GeoServer Importer Extension - Transforms
-  description: The Importer extension gives a GeoServer administrator an alternate, more-streamlined method for uploading and configuring new layers. The main endpoint manages individual import jobs. The importer extension is an optional install and may not be available on all deployments of GeoServer
+  description: The Importer extension gives a GeoServer administrator an alternate, more-streamlined method for uploading and configuring new layers. The transforms endpoint manages data transforms applied to sindividual import jobs. The importer extension is an optional install and may not be available on all deployments of GeoServer
 
 paths:
   /imports/{importId}/tasks/{taskId}/transforms:
@@ -16,7 +16,7 @@ paths:
         - text/html
       parameters:
         - $ref: "#/parameters/ImportId"
-        - $ref: "#/parameters/TaskId"      
+        - $ref: "#/parameters/TaskId"
         - $ref: "#/parameters/ExpandParameter"
       responses:
         200:
@@ -48,10 +48,9 @@ paths:
       consumes:
         - application/json
         - text/json
-      produces:
-        - application/json
-        - text/html
       parameters:
+        - $ref: "#/parameters/ImportId"
+        - $ref: "#/parameters/TaskId"
         - $ref: "#/parameters/ExpandParameter"
         - $ref: "#/parameters/TransformParameter"
       responses:
@@ -72,12 +71,8 @@ paths:
       parameters:
         - $ref: "#/parameters/ImportId"
         - $ref: "#/parameters/TaskId"
+        - $ref: "#/parameters/TransformId"
         - $ref: "#/parameters/ExpandParameter"
-        - name: transformId
-          type: string
-          required: true
-          in: path
-          description: The transform ID
       responses:
         200:
           description: OK
@@ -94,6 +89,9 @@ paths:
         - application/json
         - text/html
       parameters:
+        - $ref: "#/parameters/ImportId"
+        - $ref: "#/parameters/TaskId"
+        - $ref: "#/parameters/TransformId"
         - $ref: "#/parameters/ExpandParameter"
         - $ref: "#/parameters/TransformParameter"
       responses:
@@ -105,6 +103,10 @@ paths:
       operationId: deleteTransform
       summary: Removes the transformation 
       description: Removes the transformation identified by {transformId} inside a task with id {taskId} within import with id {importId}
+      parameters:
+        - $ref: "#/parameters/ImportId"
+        - $ref: "#/parameters/TaskId"
+        - $ref: "#/parameters/TransformId"
       responses:
         200:
           description: OK
@@ -120,7 +122,7 @@ parameters:
     name: transformBody
     description: The transform to add.
     in: body
-    required: true          
+    required: true
     schema:
       $ref: "#/definitions/Transform"
   ImportId:
@@ -134,6 +136,12 @@ parameters:
     in: path
     description: The ID of the task
     required: true
+    type: string
+  TransformId:
+    name: transformId
+    in: path
+    description: The ID of the transform
+    required: true
     type: string 
 
 definitions:      

diff --git a/src/extension/importer/rest/src/main/java/org/geoserver/importer/rest/ImportController.java b/src/extension/importer/rest/src/main/java/org/geoserver/importer/rest/ImportController.java
@@ -87,6 +87,7 @@ public ImportWrapper getImports(@RequestParam(required=false) String expand) {
             // this means a specific lookup failed
             throw new RestException("Failed to find import context", HttpStatus.NOT_FOUND);
         } else {
+            //For ImportContext, the expand parameter is handled at the converter level. Here, we are listing contexts, and use a different (more succinct) default
             return (writer, builder, converter) -> converter.contexts(builder,(Iterator<ImportContext>)lookupContext, converter.expand(expand, 0));
         }
     }

diff --git a/...tension/importer/rest/src/main/java/org/geoserver/importer/rest/ImportTaskController.java b/...tension/importer/rest/src/main/java/org/geoserver/importer/rest/ImportTaskController.java
@@ -157,20 +157,24 @@ PutIgnoringExtensionContentNegotiationStrategy importTaskPutContentNegotiationSt
                     Arrays.asList(MediaType.APPLICATION_JSON, MediaType.TEXT_HTML));
         }
     }
+
+    /**
+     * Uploads a file as a new import task.
+     *
+     * @param id The import id
+     * @param filename The destination name of the file
+     */
     @PutMapping(path = "/{taskId:.+}")
     public Object taskPutFile(
             @PathVariable Long id,
-            @PathVariable Object taskId,
+            @PathVariable(name="taskId") Object filename,
             @RequestParam(required=false) String expand,
             HttpServletRequest request, HttpServletResponse response) {
 
         ImportContext context = context(id);
-        //TODO: Task id is the file name here. This functionality is completely undocumented
+        return acceptData(handleFileUpload(context, filename, request), context, response, expand);
-        return acceptData(handleFileUpload(context, taskId, request), context, response, expand);
     }
 
-
-
     @PutMapping(path = "/{taskId}/target")
     @ResponseStatus(HttpStatus.NO_CONTENT)
     public void targetPut(

diff --git a/...on/importer/rest/src/main/java/org/geoserver/importer/rest/ImportTransformController.java b/...on/importer/rest/src/main/java/org/geoserver/importer/rest/ImportTransformController.java
@@ -42,7 +42,6 @@ protected ImportTransformController(Importer importer) {
     public ResponseEntity postTransform(
             @PathVariable Long importId,
             @PathVariable Integer taskId,
-            @RequestParam(value = "expand", required = false) String expand,
             @RequestBody ImportTransform importTransform,
             UriComponentsBuilder builder) {
 
@@ -104,8 +103,7 @@ public ImportWrapper putTransform(
     public ResponseEntity deleteTransform(
             @PathVariable Long importId,
             @PathVariable Integer taskId,
-            @PathVariable Integer transformId,
+            @PathVariable Integer transformId) {
-            @RequestParam(value = "expand", required = false) String expand) {
 
         ImportTask task = task(importId, taskId);
         ImportTransform tx = transform(importId, taskId, transformId);