Merge pull request #168 from GIScience/swagger-tweaks

swagger tweaks: reordering and remove deprecated parameters
GIScience · Jun 22, 2021 · e5db39e · e5db39e
2 parents 1a8a9b2 + a13c9c8
commit e5db39e
Show file tree

Hide file tree

Showing 7 changed files with 15 additions and 71 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -24,6 +24,7 @@ Changelog
 * properly skip `GetControllerTest` class if `port1` parameter is absent ([#164])
 * update ohsome parent module, requires maven version 3.6 or higher ([#184])
 * update documentation([#88]) ([#150]) and endpoints graph ([#158])
+* remove deprecated request parameters from swagger definition and UI ([#168])
 
 [#55]: https://github.com/GIScience/ohsome-api/issues/55
 [#88]: https://github.com/GIScience/ohsome-api/issues/88
@@ -32,6 +33,7 @@ Changelog
 [#158]: https://github.com/GIScience/ohsome-api/issues/158
 [#164]: https://github.com/GIScience/ohsome-api/pull/164
 [#166]: https://github.com/GIScience/ohsome-api/issues/166
+[#168]: https://github.com/GIScience/ohsome-api/pull/168
 [#175]: https://github.com/GIScience/ohsome-api/issues/175
 [#184]: https://github.com/GIScience/ohsome-api/pull/184
 [#191]: https://github.com/GIScience/ohsome-api/issues/191

diff --git a/src/main/lombok/org/heigit/ohsome/ohsomeapi/config/SwaggerConfig.java b/src/main/lombok/org/heigit/ohsome/ohsomeapi/config/SwaggerConfig.java
@@ -83,12 +83,14 @@ public Docket dataAggregationDocket() {
             .basePackage("org.heigit.ohsome.ohsomeapi.controller.dataaggregation"))
         .paths(PathSelectors.any()).build().apiInfo(apiInfo()).useDefaultResponseMessages(false)
         .globalOperationParameters(defineGlobalOperationParams(false))
-        .tags(new Tag("Users Count", "Compute the count of OSM users"),
-            new Tag("Elements Area", "Compute the area of polygonal OSM elements"),
-            new Tag("Elements Length", "Compute the length of linear OSM elements"),
-            new Tag("Elements Count", "Compute the count of point/linear/polygonal OSM elements"),
-            new Tag("Elements Perimeter", "Compute the perimeter of polygonal OSM elements"),
-            new Tag("Contributions Count", "Compute the count of OSM contributions"))
+        .tags(
+            new Tag("Elements Count",
+                "Compute the count of point/linear/polygonal OSM elements", 1),
+            new Tag("Elements Length", "Compute the length of linear OSM elements", 2),
+            new Tag("Elements Area", "Compute the area of polygonal OSM elements", 3),
+            new Tag("Elements Perimeter", "Compute the perimeter of polygonal OSM elements", 4),
+            new Tag("Users Count", "Compute the count of OSM users", 5),
+            new Tag("Contributions Count", "Compute the count of OSM contributions", 6))
         .forCodeGeneration(true).globalResponseMessage(RequestMethod.GET, responseMessages)
         .globalResponseMessage(RequestMethod.POST, responseMessages);
   }
@@ -102,7 +104,7 @@ public Docket metadataDocket() {
         .apis(
             RequestHandlerSelectors.basePackage("org.heigit.ohsome.ohsomeapi.controller.metadata"))
         .paths(PathSelectors.any()).build().apiInfo(apiInfo()).useDefaultResponseMessages(false)
-        .tags(new Tag("Metadata", "Request metadata of the underlying OSHDB"))
+        .tags(new Tag("Metadata", "Request metadata of the underlying OSHDB", 1))
         .forCodeGeneration(true).globalResponseMessage(RequestMethod.GET, responseMessages);
   }
 
@@ -116,11 +118,12 @@ public Docket dataExtractionDocket() {
             .basePackage("org.heigit.ohsome.ohsomeapi.controller.dataextraction"))
         .paths(PathSelectors.any()).build().apiInfo(apiInfo()).useDefaultResponseMessages(false)
         .globalOperationParameters(defineGlobalOperationParams(true))
-        .tags(new Tag("Elements Extraction", "Direct access to the OSM data"),
+        .tags(
+            new Tag("Elements Extraction", "Direct access to the OSM data", 1),
             new Tag("Full History Elements Extraction",
-                "Direct access to the full history of the OSM data"),
+                "Direct access to the full history of the OSM data", 2),
             new Tag("Contributions Extraction",
-                "Direct access to all contributions provided to the OSM data"))
+                "Direct access to all contributions provided to the OSM data", 3))
         .forCodeGeneration(true).globalResponseMessage(RequestMethod.GET, responseMessages);
   }
 
@@ -174,15 +177,6 @@ private List<Parameter> defineGlobalOperationParams(boolean isDataExtraction) {
     globalOperationParams.add(new ParameterBuilder().name("bpolys")
         .description(ParameterDescriptions.BPOLYS).modelRef(new ModelRef(string))
         .parameterType(query).defaultValue("").required(false).build());
-    globalOperationParams.add(new ParameterBuilder().name("types")
-        .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.DEPRECATED_USE_FILTER).modelRef(new ModelRef(string))
-        .parameterType(query).defaultValue("").required(false).build());
-    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)

diff --git a/src/main/lombok/org/heigit/ohsome/ohsomeapi/controller/ParameterDescriptions.java b/src/main/lombok/org/heigit/ohsome/ohsomeapi/controller/ParameterDescriptions.java
@@ -38,10 +38,6 @@ public class ParameterDescriptions {
   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.";
   public static final String CLIP_GEOMETRY = "Boolean operator to specify whether the returned "
       + "geometries of the features should be clipped to the query's spatial boundary (‘true’), "
       + "or not (‘false’); default: ‘true’";

diff --git a/...ombok/org/heigit/ohsome/ohsomeapi/controller/dataaggregation/elements/AreaController.java b/...ombok/org/heigit/ohsome/ohsomeapi/controller/dataaggregation/elements/AreaController.java
@@ -305,12 +305,6 @@ public Response areaDensityGroupByTag(HttpServletRequest servletRequest,
           + "filter",
       nickname = "areaRatio", response = RatioResponse.class)
   @ApiImplicitParams({
-      @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 = "filter", value = ParameterDescriptions.FILTER,
           defaultValue = DefaultSwaggerParameters.BUILDING_FILTER, paramType = "query",
           dataType = "string", required = false),
@@ -339,12 +333,6 @@ public Response areaRatio(HttpServletRequest servletRequest, HttpServletResponse
   @ApiOperation(value = "Ratio of the area of OSM elements grouped by the boundary",
       nickname = "areaRatioGroupByBoundary", response = RatioGroupByBoundaryResponse.class)
   @ApiImplicitParams({
-      @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 = "filter", value = ParameterDescriptions.FILTER,
           defaultValue = DefaultSwaggerParameters.BUILDING_FILTER, paramType = "query",
           dataType = "string", required = false),

diff --git a/...mbok/org/heigit/ohsome/ohsomeapi/controller/dataaggregation/elements/CountController.java b/...mbok/org/heigit/ohsome/ohsomeapi/controller/dataaggregation/elements/CountController.java
@@ -307,12 +307,6 @@ public Response countDensityGroupByTag(HttpServletRequest servletRequest,
   @ApiOperation(value = "Ratio of OSM elements satisfying filter2 within items selected by filter",
       nickname = "countRatio", response = RatioResponse.class)
   @ApiImplicitParams({
-      @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 = "filter", value = ParameterDescriptions.FILTER,
           defaultValue = DefaultSwaggerParameters.BUILDING_FILTER, paramType = "query",
           dataType = "string", required = false),
@@ -341,12 +335,6 @@ public Response countRatio(HttpServletRequest servletRequest, HttpServletRespons
   @ApiOperation(value = "Ratio of OSM elements grouped by the boundary",
       nickname = "countRatioGroupByBoundary", response = RatioGroupByBoundaryResponse.class)
   @ApiImplicitParams({
-      @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 = "filter", value = ParameterDescriptions.FILTER,
           defaultValue = DefaultSwaggerParameters.BUILDING_FILTER, paramType = "query",
           dataType = "string", required = false),

diff --git a/...bok/org/heigit/ohsome/ohsomeapi/controller/dataaggregation/elements/LengthController.java b/...bok/org/heigit/ohsome/ohsomeapi/controller/dataaggregation/elements/LengthController.java
@@ -301,12 +301,6 @@ public Response lengthDensityGroupByTag(HttpServletRequest servletRequest,
   @ApiOperation(value = "Ratio of OSM elements satisfying filter2 within items selected by filter",
       nickname = "lengthRatio", response = RatioResponse.class)
   @ApiImplicitParams({
-      @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 = "filter", value = ParameterDescriptions.FILTER,
           defaultValue = DefaultSwaggerParameters.HIGHWAY_FILTER2, paramType = "query",
           dataType = "string", required = false),
@@ -335,12 +329,6 @@ public Response lengthRatio(HttpServletRequest servletRequest,
   @ApiOperation(value = "Ratio of the length of OSM elements grouped by the boundary",
       nickname = "lengthRatioGroupByBoundary", response = RatioGroupByBoundaryResponse.class)
   @ApiImplicitParams({
-      @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 = "filter", value = ParameterDescriptions.FILTER,
           defaultValue = DefaultSwaggerParameters.HIGHWAY_FILTER2, paramType = "query",
           dataType = "string", required = false),

diff --git a/.../org/heigit/ohsome/ohsomeapi/controller/dataaggregation/elements/PerimeterController.java b/.../org/heigit/ohsome/ohsomeapi/controller/dataaggregation/elements/PerimeterController.java
@@ -305,12 +305,6 @@ public Response perimeterDensityGroupByTag(HttpServletRequest servletRequest,
   @ApiOperation(value = "Ratio of OSM elements satisfying filter2 within items selected by filter",
       nickname = "perimeterRatio", response = RatioResponse.class)
   @ApiImplicitParams({
-      @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 = "filter", value = ParameterDescriptions.FILTER,
           defaultValue = DefaultSwaggerParameters.BUILDING_FILTER, paramType = "query",
           dataType = "string", required = false),
@@ -339,12 +333,6 @@ public Response perimeterRatio(HttpServletRequest servletRequest,
   @ApiOperation(value = "Ratio of the perimeter of OSM elements grouped by the boundary",
       nickname = "perimeterRatioGroupByBoundary", response = RatioGroupByBoundaryResponse.class)
   @ApiImplicitParams({
-      @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 = "filter", value = ParameterDescriptions.FILTER,
           defaultValue = DefaultSwaggerParameters.BUILDING_FILTER, paramType = "query",
           dataType = "string", required = false),