chore(api): Springfox to openapi migration

openrouteservice/pom.xml

@@ -559,10 +559,11 @@
             <artifactId>micrometer-registry-prometheus</artifactId>
         </dependency>
         <dependency>
-            <groupId>io.springfox</groupId>
-            <artifactId>springfox-swagger2</artifactId>
-            <version>3.0.0</version>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-ui</artifactId>
+            <version>1.6.15</version>
         </dependency>
+
         <dependency>
             <groupId>com.fasterxml.jackson.datatype</groupId>
             <artifactId>jackson-datatype-jsr310</artifactId>

openrouteservice/src/main/java/org/heigit/ors/api/OpenApiConfiguration.java

@@ -0,0 +1,104 @@
+/*
+ * This file is part of Openrouteservice.
+ *
+ * Openrouteservice is free software; you can redistribute it and/or modify it under the terms of the
+ * GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License along with this library;
+ * if not, see <https://www.gnu.org/licenses/>.
+ */
+
+package org.heigit.ors.api;
+
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.SpecVersion;
+import io.swagger.v3.oas.models.info.Contact;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.info.License;
+import io.swagger.v3.oas.models.servers.Server;
+import org.heigit.ors.config.AppConfig;
+import org.springdoc.core.GroupedOpenApi;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import javax.servlet.ServletContext;
+import java.util.ArrayList;
+import java.util.List;
+
+@Configuration
+public class OpenApiConfiguration {
+
+    private static final String SERVICE_NAME = "Openrouteservice";
+    String swaggerDocumentationUrl = AppConfig.getGlobal().getParameter("info", "swagger_documentation_url");
+    String swaggerDocumentationAddAutogeneratedUrl = AppConfig.getGlobal().getParameter("info", "swagger_documentation_add_autogenerated_url");
+
+    @Bean
+    public OpenAPI customOpenAPI(ServletContext servletContext) {
+        return new OpenAPI(SpecVersion.V31)
+                .servers(generateServers(servletContext))
+                .info(apiInfo());
+    }
+
+    /**
+     * This gives a properly versioned swagger endpoint at api-docs/v2 for the ors v2 version.
+     * To introduce, e.g., v3 just use this function and replace v2 with v3.
+     */
+    @Bean
+    public GroupedOpenApi orsV2ApiPath() {
+        String[] paths = {"/v2/**"};
+        return GroupedOpenApi.builder().group("v2").pathsToMatch(paths)
+                .build();
+    }
+
+    /**
+     * This function provides the API v2 at the root api-docs/ path, as this was the old path of service the swagger.
+     * For proper API versioning see orsV2ApiPath().
+     */
+    @Bean
+    public GroupedOpenApi oldOrsV2ApiPath() {
+        String[] paths = {"/v2/**"};
+        return GroupedOpenApi.builder().group("").pathsToMatch(paths)
+                .build();
+    }
+
+    private List<Server> generateServers(ServletContext servletContext) {
+        ArrayList<Server> listOfServers = new ArrayList<>();
+        if (swaggerDocumentationUrl != null) {
+            Server customApi = new Server().url(swaggerDocumentationUrl).description("Custom server url");
+            listOfServers.add(customApi);
+        }
+        if (Boolean.parseBoolean(swaggerDocumentationAddAutogeneratedUrl)) {
+            Server localhostServer = new Server().url(servletContext.getContextPath()).description("Auto generated server url");
+            listOfServers.add(localhostServer);
+        }
+        return listOfServers;
+    }
+
+    private Info apiInfo() {
+        return new Info()
+                .title(SERVICE_NAME)
+                .description("This is the openrouteservice API documentation")
+                .version("2")
+                .contact(apiContact())
+                .license(apiLicence());
+    }
+
+    private License apiLicence() {
+        return new License()
+                .name("MIT Licence")
+                .url("https://opensource.org/licenses/mit-license.php");
+    }
+
+    private Contact apiContact() {
+        return new Contact()
+                .name(SERVICE_NAME)
+                .email("enquiry@openrouteservice.heigit.org")
+                .url("https://github.com/GIScience/openrouteservice");
+    }
+}
+

openrouteservice/src/main/java/org/heigit/ors/api/controllers/CentralityAPI.java

@@ -19,14 +19,22 @@
 import com.fasterxml.jackson.databind.exc.InvalidFormatException;
 import com.fasterxml.jackson.databind.exc.MismatchedInputException;
 import com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException;
-import io.swagger.annotations.*;
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.heigit.ors.api.errors.CommonResponseEntityExceptionHandler;
 import org.heigit.ors.api.requests.centrality.CentralityRequest;
 import org.heigit.ors.api.requests.common.APIEnums;
 import org.heigit.ors.api.responses.centrality.json.JsonCentralityResponse;
 import org.heigit.ors.centrality.CentralityErrorCodes;
 import org.heigit.ors.centrality.CentralityResult;
 import org.heigit.ors.exceptions.*;
+import org.springdoc.core.annotations.RouterOperation;
 import org.springframework.core.convert.ConversionFailedException;
 import org.springframework.http.ResponseEntity;
 import org.springframework.http.converter.HttpMessageConversionException;
@@ -37,64 +45,73 @@
 import javax.servlet.http.HttpServletResponse;
 
 @RestController
-@Api(value = "Centrality Service", tags = "Centrality")
-@SwaggerDefinition(tags = {
-        @Tag(name = "Centrality", description = "Get node centrality for different modes of transport")
+@OpenAPIDefinition(tags = {
+        @Tag(name = "Centrality Service", description = "Get node centrality for different modes of transport")
 })
 @RequestMapping("/v2/centrality")
-@ApiResponses({
-        @ApiResponse(code = 400, message = "The request is incorrect and therefore can not be processed."),
-        @ApiResponse(code = 404, message = "An element could not be found. If possible, a more detailed error code is provided."),
-        @ApiResponse(code = 405, message = "The specified HTTP method is not supported. For more details, refer to the EndPoint documentation."),
-        @ApiResponse(code = 413, message = "The request is larger than the server is able to process, the data provided in the request exceeds the capacity limit."),
-        @ApiResponse(code = 500, message = "An unexpected error was encountered and a more detailed error code is provided."),
-        @ApiResponse(code = 501, message = "Indicates that the server does not support the functionality needed to fulfill the request."),
-        @ApiResponse(code = 503, message = "The server is currently unavailable due to overload or maintenance.")
-})
+@ApiResponse(responseCode = "400", description = "The request is incorrect and therefore can not be processed.")
+@ApiResponse(responseCode = "404", description = "An element could not be found. If possible, a more detailed error code is provided.")
+@ApiResponse(responseCode = "405", description = "The specified HTTP method is not supported. For more details, refer to the EndPoint documentation.")
+@ApiResponse(responseCode = "413", description = "The request is larger than the server is able to process, the data provided in the request exceeds the capacity limit.")
+@ApiResponse(responseCode = "500", description = "An unexpected error was encountered and a more detailed error code is provided.")
+@ApiResponse(responseCode = "501", description = "Indicates that the server does not support the functionality needed to fulfill the request.")
+@ApiResponse(responseCode = "503", description = "The server is currently unavailable due to overload or maintenance.")
 public class CentralityAPI {
     static final CommonResponseEntityExceptionHandler errorHandler = new CommonResponseEntityExceptionHandler(CentralityErrorCodes.BASE);
 
     // generic catch methods - when extra info is provided in the url, the other methods are accessed.
     @GetMapping
-    @ApiOperation(value = "", hidden = true)
+    @Operation(summary = "", hidden = true)
     public void getGetMapping() throws MissingParameterException {
         throw new MissingParameterException(CentralityErrorCodes.MISSING_PARAMETER, "profile");
     }
 
     @PostMapping
-    @ApiOperation(value = "", hidden = true)
+    @Operation(summary = "", hidden = true)
     public String getPostMapping(@RequestBody CentralityRequest request) throws MissingParameterException {
         throw new MissingParameterException(CentralityErrorCodes.MISSING_PARAMETER, "profile");
     }
 
     // Matches any response type that has not been defined
     @PostMapping(value = "/{profile}/*")
-    @ApiOperation(value = "", hidden = true)
+    @Operation(summary = "", hidden = true)
     public void getInvalidResponseType() throws StatusCodeException {
         throw new StatusCodeException(HttpServletResponse.SC_NOT_ACCEPTABLE, CentralityErrorCodes.UNSUPPORTED_EXPORT_FORMAT, "This response format is not supported");
     }
 
     // Functional request methods
     @PostMapping(value = "/{profile}")
-    @ApiOperation(notes = "Returns an ordered list of points and centrality values within a given bounding box for a selected profile and its settings as JSON", value = "Centrality Service (POST)", httpMethod = "POST", consumes = "application/json", produces = "application/json")
-    @ApiResponses(
-            @ApiResponse(code = 200,
-                    message = "Standard response for successfully processed requests. Returns JSON.", //TODO: add docs
-                    response = JsonCentralityResponse.class)
-    )
-    public JsonCentralityResponse getDefault(@ApiParam(value = "Specifies the route profile.", required = true, example = "driving-car") @PathVariable APIEnums.Profile profile,
-                                             @ApiParam(value = "The request payload", required = true) @RequestBody CentralityRequest request) throws StatusCodeException {
+    @RouterOperation(operation = @Operation(description = "Returns an ordered list of points and centrality values within a given bounding box for a selected profile and its settings as JSON.", summary = "Centrality Service (POST)"),
+            method = RequestMethod.POST,
+            consumes = "application/json",
+            produces = "application/json")
+    @ApiResponse(responseCode = "200",
+            description = "Standard response for successfully processed requests. Returns JSON.",
+            content = {@Content(
+                    mediaType = "application/geo+json",
+                    array = @ArraySchema(schema = @Schema(implementation = JsonCentralityResponse.class))
+            )
+            })
+    public JsonCentralityResponse getDefault(@Parameter(description = "Specifies the route profile.", required = true, example = "driving-car") @PathVariable APIEnums.Profile profile,
+                                             @Parameter(description = "The request payload", required = true) @RequestBody CentralityRequest request) throws StatusCodeException {
         return getJsonCentrality(profile, request);
     }
 
     @PostMapping(value = "/{profile}/json", produces = {"application/json;charset=UTF-8"})
-    @ApiOperation(notes = "Returns an ordered list of points and centrality values within a given bounding box for a selected profile and its settings as JSON", value = "Centrality Service JSON (POST)", httpMethod = "POST", consumes = "application/json", produces = "application/json")
-    @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "JSON Response", response = JsonCentralityResponse.class)
-    })
+    @RouterOperation(operation = @Operation(description = "Returns an ordered list of points and centrality values within a given bounding box for a selected profile and its settings as JSON.", summary = "Centrality Service JSON (POST)"),
+            method = RequestMethod.POST,
+            consumes = "application/json",
+            produces = "application/json")
+    @ApiResponse(responseCode = "200",
+            description = "JSON Response.",
+            content = {@Content(
+                    mediaType = "application/geo+json",
+                    array = @ArraySchema(schema = @Schema(implementation = JsonCentralityResponse.class))
+            )
+            })
     public JsonCentralityResponse getJsonCentrality(
-            @ApiParam(value = "Specifies the profile.", required = true, example = "driving-car") @PathVariable APIEnums.Profile profile,
-            @ApiParam(value = "The request payload", required = true) @RequestBody CentralityRequest request) throws StatusCodeException {
+            @Parameter(description = "Specifies the profile.", required = true, example = "driving-car") @PathVariable APIEnums.Profile profile,
+            @Parameter(description = "The request payload", required = true) @RequestBody CentralityRequest request) throws StatusCodeException {
         request.setProfile(profile);
         request.setResponseType(APIEnums.CentralityResponseType.JSON);