Merge branch 'refactoring' into 'master'

Swagger Description Updates

See merge request giscience/big-data/ohsome/ohsome-api!22

src/main/java/org/heigit/bigspatialdata/ohsome/ohsomeapi/config/SwaggerConfig.java

@@ -33,16 +33,16 @@ public class SwaggerConfig {
   @Bean
   public Docket dataAggregationDocket() {
     ArrayList<ResponseMessage> responseMessages = defineResponseMessages();
-    return new Docket(DocumentationType.SWAGGER_2).groupName("dataAggregation").select()
+    return new Docket(DocumentationType.SWAGGER_2).groupName("Data Aggregation").select()
         .apis(RequestHandlerSelectors
             .basePackage("org.heigit.bigspatialdata.ohsome.ohsomeapi.controller.dataaggregation"))
         .paths(PathSelectors.any()).build().apiInfo(apiInfo()).useDefaultResponseMessages(false)
         .globalOperationParameters(defineGlobalOperationParams(false))
-        .tags(new Tag("users", "Data Aggregation functions on users"),
-            new Tag("elementsArea", "Area resources for polygonal objects"),
-            new Tag("elementsLength", "Length resources for line objects"),
-            new Tag("elementsCount", "Count resources for point/line/polygonal objects"),
-            new Tag("elementsPerimeter", "Perimeter resources for polygonal objects"))
+        .tags(new Tag("Users", "Compute data aggregation functions on users"),
+            new Tag("Area", "Compute the area of polygonal OSM elements"),
+            new Tag("Length", "Compute the length of linear OSM elements"),
+            new Tag("Count", "Compute the count of point/linear/polygonal OSM elements"),
+            new Tag("Perimeter", "Compute the perimeter of polygonal OSM elements"))
         .forCodeGeneration(true).globalResponseMessage(RequestMethod.GET, responseMessages)
         .globalResponseMessage(RequestMethod.POST, responseMessages);
   }
@@ -51,26 +51,26 @@ public Docket dataAggregationDocket() {
   @Bean
   public Docket metadataDocket() {
     ArrayList<ResponseMessage> responseMessages = defineResponseMessages();
-    return new Docket(DocumentationType.SWAGGER_2).groupName("metadata").select()
+    return new Docket(DocumentationType.SWAGGER_2).groupName("Metadata").select()
         .apis(RequestHandlerSelectors
             .basePackage("org.heigit.bigspatialdata.ohsome.ohsomeapi.controller.metadata"))
         .paths(PathSelectors.any()).build().apiInfo(apiInfo()).useDefaultResponseMessages(false)
-        .tags(new Tag("metadata", "")).forCodeGeneration(true)
-        .globalResponseMessage(RequestMethod.GET, responseMessages);
+        .tags(new Tag("Metadata", "Request metadata of the underlying OSHDB"))
+        .forCodeGeneration(true).globalResponseMessage(RequestMethod.GET, responseMessages);
   }
 
   /** Creates the Swagger2 documentation for the data extraction resources. */
   @Bean
   public Docket rawDataDocket() {
     ArrayList<ResponseMessage> responseMessages = defineResponseMessages();
-    return new Docket(DocumentationType.SWAGGER_2).groupName("dataExtraction").select()
+    return new Docket(DocumentationType.SWAGGER_2).groupName("Data Extraction").select()
         .apis(RequestHandlerSelectors
             .basePackage("org.heigit.bigspatialdata.ohsome.ohsomeapi.controller.rawdata"))
         .paths(PathSelectors.any()).build().apiInfo(apiInfo()).useDefaultResponseMessages(false)
         .globalOperationParameters(defineGlobalOperationParams(true))
-        .tags(new Tag("dataExtraction", "Direct access to OSM data"),
-            new Tag("dataExtractionFullHistory",
-                "Direct access to the full-history of each OSM object"))
+        .tags(new Tag("Data Extraction", "Direct access to the OSM data"),
+            new Tag("Full-History Data Extraction",
+                "Direct access to the full-history of the OSM data"))
         .forCodeGeneration(true).globalResponseMessage(RequestMethod.GET, responseMessages);
   }
 

src/main/java/org/heigit/bigspatialdata/ohsome/ohsomeapi/controller/dataaggregation/AreaController.java

@@ -25,7 +25,7 @@
  * Controller containing the GET and POST servletRequest handling methods, which are mapped to
  * "/elements/area".
  */
-@Api(tags = "elementsArea")
+@Api(tags = "Area")
 @RestController
 @RequestMapping("/elements/area")
 public class AreaController {
@@ -93,7 +93,7 @@ public Response areaGroupByBoundary(HttpServletRequest servletRequest,
    * @return {@link org.heigit.bigspatialdata.ohsome.ohsomeapi.output.dataaggregationresponse.Response
    *         Response}
    */
-  @ApiOperation(value = "Area of OSM elements in meter grouped by the boundary and the tag",
+  @ApiOperation(value = "Area of OSM elements grouped by the boundary and the tag",
       nickname = "areaGroupByBoundaryGroupByTag", response = GroupByResponse.class)
   @ApiImplicitParams({
       @ApiImplicitParam(name = "groupByKey", value = ParameterDescriptions.GROUP_BY_KEY_DESCR,
@@ -206,7 +206,7 @@ public Response areaShareGroupByBoundary(HttpServletRequest servletRequest,
   }
 
   /**
-   * Gives the density of selected items (area of items divided by the total area in
+   * Gives the density of OSM elements (area of items divided by the total area in
    * square-kilometers).
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
@@ -227,7 +227,7 @@ public Response areaDensity(HttpServletRequest servletRequest,
   }
 
   /**
-   * Gives the density of selected items grouped by the OSM type.
+   * Gives the density of OSM elements grouped by the OSM type.
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
@@ -245,7 +245,7 @@ public Response areaDensityGroupByType(HttpServletRequest servletRequest,
   }
 
   /**
-   * Gives the density of selected items grouped by the boundary parameter (bounding
+   * Gives the density of OSM elements grouped by the boundary parameter (bounding
    * box/circle/polygon).
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
@@ -254,7 +254,7 @@ public Response areaDensityGroupByType(HttpServletRequest servletRequest,
    *         Response}
    */
   @ApiOperation(
-      value = "Density of selected items grouped by the boundary (bboxes, bcircles, or bpolys)",
+      value = "Density of OSM elements grouped by the boundary (bboxes, bcircles, or bpolys)",
       nickname = "areaDensityGroupByBoundary", response = GroupByResponse.class)
   @RequestMapping(value = "/density/groupBy/boundary",
       method = {RequestMethod.GET, RequestMethod.POST}, produces = {"application/json", "text/csv"})
@@ -265,7 +265,7 @@ public Response areaDensityGroupByBoundary(HttpServletRequest servletRequest,
   }
 
   /**
-   * Gives the density of selected items grouped by the boundary and the tag.
+   * Gives the density of OSM elements grouped by the boundary and the tag.
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
@@ -289,14 +289,14 @@ public Response countDensityGroupByBoundaryGroupByTag(HttpServletRequest servlet
   }
 
   /**
-   * Gives the density of selected items grouped by the tag.
+   * Gives the density of OSM elements grouped by the tag.
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
    * @return {@link org.heigit.bigspatialdata.ohsome.ohsomeapi.output.dataaggregationresponse.Response
    *         Response}
    */
-  @ApiOperation(value = "Density of selected items grouped by the tag",
+  @ApiOperation(value = "Density of OSM elements grouped by the tag",
       nickname = "areaDensityGroupByTag", response = GroupByResponse.class)
   @ApiImplicitParams({
       @ApiImplicitParam(name = "groupByKey", value = ParameterDescriptions.GROUP_BY_KEY_DESCR,
@@ -313,7 +313,7 @@ public Response areaDensityGroupByTag(HttpServletRequest servletRequest,
   }
 
   /**
-   * Gives the ratio of selected items satisfying types2, keys2 and values2 within items selected by
+   * Gives the ratio of OSM elements satisfying types2, keys2 and values2 within items selected by
    * types, keys and values.
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
@@ -322,7 +322,7 @@ public Response areaDensityGroupByTag(HttpServletRequest servletRequest,
    *         Response}
    */
   @ApiOperation(
-      value = "Ratio of selected items satisfying types2, keys2 and values2 "
+      value = "Ratio of OSM elements satisfying types2, keys2 and values2 "
           + "within items selected by types, keys and values",
       nickname = "areaRatio", response = RatioResponse.class)
   @ApiImplicitParams({
@@ -342,15 +342,15 @@ public Response areaRatio(HttpServletRequest servletRequest, HttpServletResponse
   }
 
   /**
-   * Gives the ratio of the area of selected items satisfying types2, keys2 and values2 within items
+   * Gives the ratio of the area of OSM elements satisfying types2, keys2 and values2 within items
    * selected by types, keys and values grouped by the boundary.
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
    * @return {@link org.heigit.bigspatialdata.ohsome.ohsomeapi.output.dataaggregationresponse.Response
    *         Response}
    */
-  @ApiOperation(value = "Ratio of the area of selected items grouped by the boundary",
+  @ApiOperation(value = "Ratio of the area of OSM elements grouped by the boundary",
       nickname = "areaRatioGroupByBoundary", response = RatioGroupByBoundaryResponse.class)
   @ApiImplicitParams({
       @ApiImplicitParam(name = "types2", value = ParameterDescriptions.TYPES_DESCR,

src/main/java/org/heigit/bigspatialdata/ohsome/ohsomeapi/controller/dataaggregation/CountController.java

@@ -26,7 +26,7 @@
  * Controller containing the GET and POST request handling methods, which are mapped to
  * "/elements/count".
  */
-@Api(tags = "elementsCount")
+@Api(tags = "Count")
 @RestController
 @RequestMapping("/elements/count")
 public class CountController {
@@ -161,7 +161,7 @@ public Response countGroupByTag(HttpServletRequest servletRequest,
   }
 
   /**
-   * Gives the share of selected items satisfying keys2 and values2 within items selected by types,
+   * Gives the share of OSM elements satisfying keys2 and values2 within items selected by types,
    * keys and values.
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
@@ -187,7 +187,7 @@ public Response countShare(HttpServletRequest servletRequest, HttpServletRespons
   }
 
   /**
-   * Gives the share of selected items satisfying keys2 and values2 within items selected by types,
+   * Gives the share of OSM elements satisfying keys2 and values2 within items selected by types,
    * keys and values grouped by the boundary.
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
@@ -213,7 +213,7 @@ public Response countShareGroupByBoundary(HttpServletRequest servletRequest,
   }
 
   /**
-   * Gives the density of selected items (number of items divided by the total area in
+   * Gives the density of OSM elements (number of items divided by the total area in
    * square-kilometers).
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
@@ -274,7 +274,7 @@ public Response countDensityGroupByBoundary(HttpServletRequest servletRequest,
   }
 
   /**
-   * Gives the density of selected items grouped by the boundary and the tag.
+   * Gives the density of OSM elements grouped by the boundary and the tag.
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
@@ -298,7 +298,7 @@ public Response countDensityGroupByBoundaryGroupByTag(HttpServletRequest servlet
   }
 
   /**
-   * Gives the density of selected items grouped by the tag.
+   * Gives the density of OSM elements grouped by the tag.
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
@@ -322,7 +322,7 @@ public Response countDensityGroupByTag(HttpServletRequest servletRequest,
   }
 
   /**
-   * Gives the ratio of selected items satisfying types2, keys2 and values2 within items selected by
+   * Gives the ratio of OSM elements satisfying types2, keys2 and values2 within items selected by
    * types, keys and values.
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
@@ -331,7 +331,7 @@ public Response countDensityGroupByTag(HttpServletRequest servletRequest,
    *         Response}
    */
   @ApiOperation(
-      value = "Ratio of selected items satisfying types2, keys2 and values2 "
+      value = "Ratio of OSM elements satisfying types2, keys2 and values2 "
           + "within items selected by types, keys and values",
       nickname = "countRatio", response = RatioResponse.class)
   @ApiImplicitParams({
@@ -351,15 +351,15 @@ public Response countRatio(HttpServletRequest servletRequest, HttpServletRespons
   }
 
   /**
-   * Gives the ratio of selected items satisfying types2, keys2 and values2 within items selected by
+   * Gives the ratio of OSM elements satisfying types2, keys2 and values2 within items selected by
    * types, keys and values grouped by the boundary.
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
    * @return {@link org.heigit.bigspatialdata.ohsome.ohsomeapi.output.dataaggregationresponse.Response
    *         Response}
    */
-  @ApiOperation(value = "Ratio of selected items grouped by the boundary",
+  @ApiOperation(value = "Ratio of OSM elements grouped by the boundary",
       nickname = "countRatioGroupByBoundary", response = RatioGroupByBoundaryResponse.class)
   @ApiImplicitParams({
       @ApiImplicitParam(name = "format", value = ParameterDescriptions.FORMAT_DESCR,