org.heigit.ohsome.ohsomeapi.config.SwaggerConfig Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of ohsome-api Show documentation
Show all versions of ohsome-api Show documentation
A public Web-RESTful-API for "ohsome" OpenStreetMap history data.
package org.heigit.ohsome.ohsomeapi.config;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Comparator;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
import org.heigit.ohsome.ohsomeapi.Application;
import org.heigit.ohsome.ohsomeapi.controller.DefaultSwaggerParameters;
import org.heigit.ohsome.ohsomeapi.controller.ParameterDescriptions;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.context.annotation.PropertySource;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.service.Tag;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.InMemorySwaggerResourcesProvider;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/** Swagger configuration class. */
@Configuration
@EnableSwagger2
@PropertySource("classpath:application.properties")
@Primary
public class SwaggerConfig implements SwaggerResourcesProvider {
private enum OhsomeApiResourceSpec {
DATA_AGGREGATION("Data Aggregation", 1),
DATA_EXTRACTION("Data Extraction", 2),
CONTRIBUTIONS("Contributions", 3),
METADATA("Metadata", 9);
private final String name;
private final int sorting;
OhsomeApiResourceSpec(String name, int sorting) {
this.name = name;
this.sorting = sorting;
}
}
private final InMemorySwaggerResourcesProvider resourcesProvider;
private final Map resourcesSorting = new HashMap<>();
/**
* Creates swagger configuration object, initializes internal specs sorting table.
*/
@Autowired
public SwaggerConfig(InMemorySwaggerResourcesProvider resourcesProvider) {
this.resourcesProvider = resourcesProvider;
for (OhsomeApiResourceSpec spec : OhsomeApiResourceSpec.values()) {
resourcesSorting.put(spec.name, spec.sorting);
}
}
@Override
public List get() {
return resourcesProvider.get().stream()
.sorted(Comparator.comparing(r -> resourcesSorting.getOrDefault(r.getName(), 99)))
.collect(Collectors.toList());
}
/** Creates the Swagger2 documentation for the dataAggregation resources. */
@Bean
public Docket dataAggregationDocket() {
ArrayList responseMessages = defineResponseMessages();
return new Docket(DocumentationType.SWAGGER_2)
.groupName(OhsomeApiResourceSpec.DATA_AGGREGATION.name).select()
.apis(RequestHandlerSelectors
.basePackage("org.heigit.ohsome.ohsomeapi.controller.dataaggregation"))
.paths(PathSelectors.any()).build().apiInfo(apiInfo()).useDefaultResponseMessages(false)
.globalOperationParameters(defineGlobalOperationParams(false, false))
.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);
}
/** Creates the Swagger2 documentation for the metadata resources. */
@Bean
public Docket metadataDocket() {
ArrayList responseMessages = defineResponseMessages();
return new Docket(DocumentationType.SWAGGER_2)
.groupName(OhsomeApiResourceSpec.METADATA.name).select()
.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"))
.forCodeGeneration(true).globalResponseMessage(RequestMethod.GET, responseMessages);
}
/** Creates the Swagger2 documentation for the data extraction resources. */
@Bean
public Docket rawDataDocket() {
ArrayList responseMessages = defineResponseMessages();
return new Docket(DocumentationType.SWAGGER_2)
.groupName(OhsomeApiResourceSpec.DATA_EXTRACTION.name).select()
.apis(RequestHandlerSelectors.basePackage("org.heigit.ohsome.ohsomeapi.controller.rawdata"))
.paths(PathSelectors.any()).build().apiInfo(apiInfo()).useDefaultResponseMessages(false)
.globalOperationParameters(defineGlobalOperationParams(true, false))
.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);
}
/** Creates the Swagger2 documentation for the contributions resources. */
@Bean
public Docket contributionsDocket() {
ArrayList responseMessages = defineResponseMessages();
return new Docket(DocumentationType.SWAGGER_2)
.groupName(OhsomeApiResourceSpec.CONTRIBUTIONS.name).select()
.apis(RequestHandlerSelectors
.basePackage("org.heigit.ohsome.ohsomeapi.controller.contributions"))
.paths(PathSelectors.any()).build().apiInfo(apiInfo()).useDefaultResponseMessages(false)
.globalOperationParameters(defineGlobalOperationParams(true, true))
.tags(
new Tag("Contributions", "Direct access to all contributions provided to the OSM data"))
.forCodeGeneration(true).globalResponseMessage(RequestMethod.GET, responseMessages);
}
/** Defines custom response messages for the used response codes. */
private ArrayList defineResponseMessages() {
ArrayList responseMessages = new ArrayList<>();
responseMessages.add(new ResponseMessageBuilder().code(200).message("OK").build());
responseMessages.add(new ResponseMessageBuilder().code(400).message("Bad request").build());
responseMessages.add(new ResponseMessageBuilder().code(401).message("Unauthorized").build());
responseMessages.add(new ResponseMessageBuilder().code(404).message("Not found").build());
responseMessages
.add(new ResponseMessageBuilder().code(413).message("Payload too large").build());
responseMessages
.add(new ResponseMessageBuilder().code(405).message("Method not allowed").build());
responseMessages
.add(new ResponseMessageBuilder().code(500).message("Internal server error").build());
responseMessages.add(new ResponseMessageBuilder().code(501).message("Not implemented").build());
responseMessages
.add(new ResponseMessageBuilder().code(503).message("Service Unavailable").build());
return responseMessages;
}
/** Defines information about this API. */
private ApiInfo apiInfo() {
return new ApiInfo("ohsome API",
"This REST-based API aims to leverage the tools of the "
+ "OSHDB "
+ "through allowing to access some of its functionalities via HTTP requests. \n"
+ "The official documentation can be found "
+ "here. ",
Application.API_VERSION, "",
new Contact("Heidelberg Institute for Geoinformation Technology", "https://www.heigit.org",
"[email protected]"),
"License of the used data", "https://ohsome.org/copyrights", Collections.emptyList());
}
/**
* Defines the description of each parameter, which are used in all resources for the Swagger2
* documentation.
*/
private List defineGlobalOperationParams(boolean isDataExtraction,
boolean isContributions) {
final String string = "string";
final String query = "query";
List globalOperationParams = new ArrayList<>();
globalOperationParams.add(new ParameterBuilder().name("bboxes")
.description(ParameterDescriptions.BBOXES).modelRef(new ModelRef(string))
.parameterType(query).defaultValue(DefaultSwaggerParameters.BBOX).required(false).build());
globalOperationParams.add(new ParameterBuilder().name("bcircles")
.description(ParameterDescriptions.BCIRCLES).modelRef(new ModelRef(string))
.parameterType(query).defaultValue("").required(false).build());
globalOperationParams.add(new ParameterBuilder().name("bpolys")
.description(ParameterDescriptions.BPOLYS).modelRef(new ModelRef(string))
.parameterType(query).defaultValue("").required(false).build());
if (!isContributions) {
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)
.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());
if (!isDataExtraction) {
globalOperationParams
.add(new ParameterBuilder().name("time").description(ParameterDescriptions.TIME)
.modelRef(new ModelRef(string)).parameterType(query)
.defaultValue(DefaultSwaggerParameters.TIME).required(false).build());
globalOperationParams.add(new ParameterBuilder().name("format")
.description(ParameterDescriptions.FORMAT).modelRef(new ModelRef(string))
.parameterType(query).defaultValue("json").required(false).build());
} else {
globalOperationParams.add(new ParameterBuilder().name("time")
.description(ParameterDescriptions.TIME_DATA_EXTRACTION).modelRef(new ModelRef(string))
.parameterType(query).defaultValue("2016-01-01,2017-01-01").required(true).build());
globalOperationParams.add(new ParameterBuilder().name("properties")
.description(ParameterDescriptions.PROPERTIES).modelRef(new ModelRef(string))
.parameterType(query).defaultValue("tags").required(false).build());
globalOperationParams.add(new ParameterBuilder().name("clipGeometry")
.description(ParameterDescriptions.CLIP_GEOMETRY).modelRef(new ModelRef(string))
.parameterType(query).defaultValue("true").required(false).build());
}
globalOperationParams.add(new ParameterBuilder().name("showMetadata")
.description(ParameterDescriptions.SHOW_METADATA).modelRef(new ModelRef(string))
.parameterType(query).defaultValue("").required(false).build());
return globalOperationParams;
}
}