updating swagger parameter descriptions

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

@@ -98,8 +98,8 @@ private ApiInfo apiInfo() {
     return new ApiInfo("ohsome API",
         "This REST-based API aims to leverage the tools of the "
             + "<a href=\"https://github.com/GIScience/oshdb\" target=\"_blank\">OSHDB</a> "
-            + "through allowing to access some of its functionalities via HTTP requests. \n" + 
-            "The official documentation can be found "
+            + "through allowing to access some of its functionalities via HTTP requests. \n"
+            + "The official documentation can be found "
             + "<a href=\"https://docs.ohsome.org/ohsome-api/stable\" target=\"_blank\">here</a>. ",
         Application.API_VERSION, "",
         new Contact("Heidelberg Institute for Geoinformation Technology", "https://www.heigit.org",
@@ -125,17 +125,18 @@ private List<Parameter> defineGlobalOperationParams(boolean isDataExtraction) {
         .description(ParameterDescriptions.BPOLYS).modelRef(new ModelRef(string))
         .parameterType(query).defaultValue("").required(false).build());
     globalOperationParams.add(new ParameterBuilder().name("types")
-        .description(ParameterDescriptions.TYPES).modelRef(new ModelRef(string)).allowMultiple(true)
-        .parameterType(query).defaultValue(DefaultSwaggerParameters.TYPE).required(false).build());
+        .description(ParameterDescriptions.DEPRECATED_USE_FILTER).modelRef(new ModelRef(string))
+        .allowMultiple(true).parameterType(query).defaultValue("").required(false).build());
     globalOperationParams.add(new ParameterBuilder().name("keys")
-        .description(ParameterDescriptions.KEYS).modelRef(new ModelRef(string)).parameterType(query)
-        .defaultValue("").required(false).build());
-    globalOperationParams.add(new ParameterBuilder().name("values")
-        .description(ParameterDescriptions.VALUES).modelRef(new ModelRef(string))
+        .description(ParameterDescriptions.DEPRECATED_USE_FILTER).modelRef(new ModelRef(string))
         .parameterType(query).defaultValue("").required(false).build());
-    globalOperationParams.add(new ParameterBuilder().name("filter")
-        .description(ParameterDescriptions.FILTER).modelRef(new ModelRef(string))
+    globalOperationParams.add(new ParameterBuilder().name("values")
+        .description(ParameterDescriptions.DEPRECATED_USE_FILTER).modelRef(new ModelRef(string))
         .parameterType(query).defaultValue("").required(false).build());
+    globalOperationParams
+        .add(new ParameterBuilder().name("filter").description(ParameterDescriptions.FILTER)
+            .modelRef(new ModelRef(string)).parameterType(query)
+            .defaultValue(DefaultSwaggerParameters.TYPE_FILTER).required(false).build());
     globalOperationParams.add(new ParameterBuilder().name("timeout")
         .description(ParameterDescriptions.TIMEOUT).modelRef(new ModelRef(string))
         .parameterType(query).defaultValue("").required(false).build());
@@ -158,7 +159,7 @@ private List<Parameter> defineGlobalOperationParams(boolean isDataExtraction) {
     globalOperationParams.add(
         new ParameterBuilder().name("showMetadata").description(ParameterDescriptions.SHOW_METADATA)
             .modelRef(new ModelRef(string)).parameterType(query)
-            .defaultValue(DefaultSwaggerParameters.SHOW_METADATA).required(false).build());
+            .defaultValue("").required(false).build());
     return globalOperationParams;
   }
 }

src/main/java/org/heigit/ohsome/ohsomeapi/controller/DefaultSwaggerParameters.java

@@ -4,13 +4,15 @@
 public class DefaultSwaggerParameters {
 
   public static final String BBOX = "8.625,49.3711,8.7334,49.4397";
-  public static final String TYPE = "way";
   public static final String HIGHWAY_KEY = "highway";
   public static final String BUILDING_KEY = "building";
   public static final String HOUSENUMBER_KEY = "addr:housenumber";
   public static final String RESIDENTIAL_VALUE = "residential";
+  public static final String TYPE_FILTER = "type:way";
+  public static final String HIGHWAY_FILTER = "highway=residential";
+  public static final String BUILDING_FILTER = "building=*";
+  public static final String HOUSENUMBER_FILTER = "type:node and \"addr:housenumber=*\"";
   public static final String TIME = "2014-01-01/2017-01-01/P1Y";
-  public static final String SHOW_METADATA = "false";
 
   private DefaultSwaggerParameters() {
     throw new IllegalStateException("Utility class");

src/main/java/org/heigit/ohsome/ohsomeapi/controller/ParameterDescriptions.java

@@ -17,7 +17,7 @@ public class ParameterDescriptions {
           + "(one boundary parameter must be defined)";
   public static final String TYPES =
       "OSM type(s) 'node' and/or 'way' and/or 'relation' OR simple feature type(s) 'point' and/or "
-      + "'line' and/or 'polygon'; default: all three OSM types";
+          + "'line' and/or 'polygon'; default: all three OSM types";
   public static final String KEYS = "OSM key(s) e.g.: 'highway', 'building'; default: no key";
   public static final String GROUP_BY_KEY = "OSM key e.g.: 'highway', 'building'; no default "
       + "value (one groupByKey parameter must be defined)";
@@ -27,17 +27,20 @@ public class ParameterDescriptions {
       "ISO-8601 conform timestring(s); default: latest timestamp within dataset";
   public static final String TIME_DATA_EXTRACTION =
       "ISO-8601 conform timestring(s) defining timestamps (/elements), "
-      + "or intervals (/elementsFullHistory); no default value";
+          + "or intervals (/elementsFullHistory); no default value";
   public static final String FORMAT =
       "Output format geojson (for /groupBy/boundary resources only), csv, or json; default: json";
   public static final String PROPERTIES =
       "List of possible property-groups added to each OSM-element: 'tags' and/or 'metadata'; "
           + "default: no property";
-  public static final String SHOW_METADATA =
-      "Boolean operator 'true' or 'false'; default: 'false'";
-  public static final String TIMEOUT = "Custom timeout in seconds;";
+  public static final String SHOW_METADATA = "Boolean operator 'true' or 'false'; default: 'false'";
+  public static final String TIMEOUT = "Custom timeout in seconds; no default value";
   public static final String FILTER = "Combines several attributive filters, e.g. OSM type, "
       + "the geometry (simple feature) type, as well as the OSM tag; no default value";
+  public static final String DEPRECATED_USE_FILTER = "This parameter has been deprecated since "
+      + "v1.0. We encourage you to use the new parameter 'filter' instead.";
+  public static final String DEPRECATED_USE_FILTER2 = "This parameter has been deprecated since "
+      + "v1.0. We encourage you to use the new parameter 'filter2' instead.";
 
   private ParameterDescriptions() {
     throw new IllegalStateException("Utility class");

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

@@ -34,8 +34,7 @@ public class AreaController {
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
-   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response
-   *         Response}
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response Response}
    */
   @ApiOperation(value = "Area of OSM elements", nickname = "area",
       response = DefaultAggregationResponse.class)
@@ -52,8 +51,7 @@ public Response area(HttpServletRequest servletRequest, HttpServletResponse serv
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
-   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response
-   *         Response}
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response Response}
    */
   @ApiOperation(value = "Area of OSM elements grouped by the type", nickname = "areaGroupByType",
       response = GroupByResponse.class)
@@ -70,8 +68,7 @@ public Response areaGroupByType(HttpServletRequest servletRequest,
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
-   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response
-   *         Response}
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response Response}
    */
   @ApiOperation(
       value = "Area of OSM elements grouped by the boundary (bboxes, bcircles, or bpolys)",
@@ -89,8 +86,7 @@ public Response areaGroupByBoundary(HttpServletRequest servletRequest,
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
-   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response
-   *         Response}
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response Response}
    */
   @ApiOperation(value = "Area of OSM elements grouped by the boundary and the tag",
       nickname = "areaGroupByBoundaryGroupByTag", response = GroupByResponse.class)
@@ -113,8 +109,7 @@ public Response countGroupByBoundaryGroupByTag(HttpServletRequest servletRequest
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
-   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response
-   *         Response}
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response Response}
    */
   @ApiOperation(value = "Area of OSM elements grouped by the key", nickname = "areaGroupByKey",
       response = GroupByResponse.class)
@@ -134,8 +129,7 @@ public Response areaGroupByKey(HttpServletRequest servletRequest,
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
-   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response
-   *         Response }
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response Response }
    */
   @ApiOperation(value = "Area of OSM elements grouped by the tag", nickname = "areaGroupByTag",
       response = GroupByResponse.class)
@@ -159,8 +153,7 @@ public Response areaGroupByTag(HttpServletRequest servletRequest,
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
-   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response
-   *         Response}
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response Response}
    */
   @ApiOperation(
       value = "Density of OSM elements (area of elements divided "
@@ -179,8 +172,7 @@ public Response areaDensity(HttpServletRequest servletRequest,
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
-   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response
-   *         Response}
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response Response}
    */
   @ApiOperation(value = "Density of OSM elements grouped by the type",
       nickname = "areaDensityGroupByType", response = GroupByResponse.class)
@@ -198,8 +190,7 @@ public Response areaDensityGroupByType(HttpServletRequest servletRequest,
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
-   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response
-   *         Response}
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response Response}
    */
   @ApiOperation(
       value = "Density of OSM elements grouped by the boundary (bboxes, bcircles, or bpolys)",
@@ -217,8 +208,7 @@ public Response areaDensityGroupByBoundary(HttpServletRequest servletRequest,
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
-   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response
-   *         Response}
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response Response}
    */
   @ApiOperation(value = "Density of OSM elements grouped by the boundary and the tag",
       nickname = "areaDensityGroupByBoundaryGroupByTag", response = GroupByResponse.class)
@@ -241,8 +231,7 @@ public Response countDensityGroupByBoundaryGroupByTag(HttpServletRequest servlet
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
-   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response
-   *         Response}
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response Response}
    */
   @ApiOperation(value = "Density of OSM elements grouped by the tag",
       nickname = "areaDensityGroupByTag", response = GroupByResponse.class)
@@ -266,22 +255,21 @@ public Response areaDensityGroupByTag(HttpServletRequest servletRequest,
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
-   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response
-   *         Response}
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response Response}
    */
   @ApiOperation(
       value = "Ratio of the area of OSM elements satisfying types2, keys2 and values2 (or filter2)"
           + "within items selected by types, keys and values (or filter)",
       nickname = "areaRatio", response = RatioResponse.class)
   @ApiImplicitParams({
-      @ApiImplicitParam(name = "types2", value = ParameterDescriptions.TYPES,
-          defaultValue = "relation", paramType = "query", dataType = "string", required = false),
-      @ApiImplicitParam(name = "keys2", value = ParameterDescriptions.KEYS,
-          defaultValue = DefaultSwaggerParameters.BUILDING_KEY, paramType = "query",
-          dataType = "string", required = false),
-      @ApiImplicitParam(name = "values2", value = ParameterDescriptions.VALUES, defaultValue = "",
-          paramType = "query", dataType = "string", required = false),
-      @ApiImplicitParam(name = "filter2", value = ParameterDescriptions.FILTER, defaultValue = "",
+      @ApiImplicitParam(name = "types2", value = ParameterDescriptions.DEPRECATED_USE_FILTER2,
+          defaultValue = "", paramType = "query", dataType = "string", required = false),
+      @ApiImplicitParam(name = "keys2", value = ParameterDescriptions.DEPRECATED_USE_FILTER2,
+          defaultValue = "", paramType = "query", dataType = "string", required = false),
+      @ApiImplicitParam(name = "values2", value = ParameterDescriptions.DEPRECATED_USE_FILTER2,
+          defaultValue = "", paramType = "query", dataType = "string", required = false),
+      @ApiImplicitParam(name = "filter2", value = ParameterDescriptions.FILTER,
+          defaultValue = "type:relation and " + DefaultSwaggerParameters.BUILDING_FILTER,
           paramType = "query", dataType = "string", required = false)})
   @RequestMapping(value = "/ratio", method = {RequestMethod.GET, RequestMethod.POST},
       produces = {"application/json", "text/csv"})
@@ -297,22 +285,20 @@ public Response areaRatio(HttpServletRequest servletRequest, HttpServletResponse
    * 
    * @param servletRequest <code>HttpServletRequest</code> of the incoming request
    * @param servletResponse <code>HttpServletResponse</code> of the outgoing response
-   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response
-   *         Response}
+   * @return {@link org.heigit.ohsome.ohsomeapi.output.dataaggregationresponse.Response Response}
    */
   @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,
-          defaultValue = DefaultSwaggerParameters.TYPE, paramType = "query", dataType = "string",
-          required = false),
-      @ApiImplicitParam(name = "keys2", value = ParameterDescriptions.KEYS,
-          defaultValue = DefaultSwaggerParameters.BUILDING_KEY, paramType = "query",
-          dataType = "string", required = false),
-      @ApiImplicitParam(name = "values2", value = ParameterDescriptions.VALUES, defaultValue = "",
-          paramType = "query", dataType = "string", required = false),
-      @ApiImplicitParam(name = "filter2", value = ParameterDescriptions.FILTER, defaultValue = "",
-          paramType = "query", dataType = "string", required = false)})
+      @ApiImplicitParam(name = "types2", value = ParameterDescriptions.DEPRECATED_USE_FILTER2,
+          defaultValue = "", paramType = "query", dataType = "string", required = false),
+      @ApiImplicitParam(name = "keys2", value = ParameterDescriptions.DEPRECATED_USE_FILTER2,
+          defaultValue = "", paramType = "query", dataType = "string", required = false),
+      @ApiImplicitParam(name = "values2", value = ParameterDescriptions.DEPRECATED_USE_FILTER2,
+          defaultValue = "", paramType = "query", dataType = "string", required = false),
+      @ApiImplicitParam(name = "filter2", value = ParameterDescriptions.FILTER,
+          defaultValue = DefaultSwaggerParameters.BUILDING_FILTER, paramType = "query",
+          dataType = "string", required = false)})
   @RequestMapping(value = "/ratio/groupBy/boundary",
       method = {RequestMethod.GET, RequestMethod.POST}, produces = {"application/json", "text/csv"})
   public Response areaRatioGroupByBoundary(HttpServletRequest servletRequest,