Skip to content

Commit

Permalink
chore(api): Springfox to openapi migration
Browse files Browse the repository at this point in the history
  • Loading branch information
MichaelsJP committed Mar 31, 2023
1 parent 6990217 commit 0839c7b
Show file tree
Hide file tree
Showing 59 changed files with 831 additions and 733 deletions.
7 changes: 4 additions & 3 deletions openrouteservice/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
Original file line number Diff line number Diff line change
@@ -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");
}
}

110 changes: 0 additions & 110 deletions openrouteservice/src/main/java/org/heigit/ors/api/SwaggerConfig.java

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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);

Expand Down
Loading

0 comments on commit 0839c7b

Please sign in to comment.