Merge pull request #820 from EBISPOT/add-v2-api-documentation

Add Swagger Documentation for V2 API

backend/src/main/java/uk/ac/ebi/spot/ols/config/SwaggerConfig.java

@@ -23,7 +23,7 @@ public OpenAPI customOpenApi(ServletContext context) {
                 .addServersItem(new Server().url(serverUrl))
                 .info(new Info()
                         .title("OLS Service")
-                        .description("REST API for OLS")
+                        .description("REST API for OLS. Please see <a href='"+OLS4_SERVER_URL+"/defined-response-fields' target='_blank'> this page</a> for defined response field in OLS.")
                         .version("3.0")
                         .termsOfService("https://www.ebi.ac.uk/about/terms-of-use/")
                         .license(new License()

backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2ClassController.java

@@ -1,5 +1,7 @@
 package uk.ac.ebi.spot.ols.controller.api.v2;
 
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.rest.webmvc.ResourceNotFoundException;
@@ -10,10 +12,7 @@
 import org.springframework.http.ResponseEntity;
 import org.springframework.stereotype.Controller;
 import org.springframework.util.MultiValueMap;
-import org.springframework.web.bind.annotation.PathVariable;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RequestMethod;
-import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.*;
 import org.springframework.web.util.UriUtils;
 import uk.ac.ebi.spot.ols.controller.api.v2.helpers.DynamicQueryHelper;
 import uk.ac.ebi.spot.ols.controller.api.v2.responses.V2PagedAndFacetedResponse;
@@ -30,7 +29,8 @@
 
 import static uk.ac.ebi.ols.shared.DefinedFields.*;
 
-@Controller
+@Tag(name = "V2 Class Controller", description = "This endpoint provides access to class information.")
+@RestController
 @RequestMapping("/api/v2")
 public class V2ClassController {
 
@@ -41,12 +41,34 @@ public class V2ClassController {
     public HttpEntity<V2PagedAndFacetedResponse<V2Entity>> getClasses(
             @PageableDefault(size = 20, page = 0) Pageable pageable,
             @RequestParam(value = "lang", required = false, defaultValue = "en") String lang,
-            @RequestParam(value = "search", required = false) String search,
-            @RequestParam(value = "searchFields", required = false) String searchFields,
-            @RequestParam(value = "boostFields", required = false) String boostFields,
-            @RequestParam(value = "exactMatch", required = false, defaultValue = "false") boolean exactMatch,
-            @RequestParam(value = "includeObsoleteEntities", required = false, defaultValue = "false") boolean includeObsoleteEntities,
-            @RequestParam MultiValueMap<String,String> searchProperties
+            @RequestParam(value = "search", required = false)
+            @Parameter(name="search",
+                    description = "This parameter specify the search query text.",
+                    example = "liver disease") String search,
+            @RequestParam(value = "searchFields", required = false)
+            @Parameter(name = "searchFields",
+                    description = "This parameter is a white space separated list of fields to search in. " +
+                            "The fields are weighted equally. The fields are defined in the schema. " +
+                            "The default fields are label and definition. " +
+                            "The fields weights can be boosted by appending a caret ^ and a positive integer to the field name. " +
+                            "For example, label^3 synonyms^2 description^1 logical_definition^1",
+                    example = "label^100 description") String searchFields,
+            @RequestParam(value = "boostFields", required = false)
+            @Parameter(name = "boostFields",
+                    description = "This parameter is a white space separated list of fields appended with a caret to boost in search. " +
+                            "The default fields are type, is_defining_ontology, label, curie, shortForm and synonym . " +
+                            "The fields weights can be boosted by appending a caret ^ and a positive integer to the field name. ",
+                    example = "label^100 curie^50") String boostFields,
+            @RequestParam(value = "exactMatch", required = false, defaultValue = "false")
+            @Parameter(name = "exactMatch",
+                    description = "As the name suggests its a boolean parameter to specify if search should be exact match or not." +
+                            "The default value is false") boolean exactMatch,
+            @RequestParam(value = "includeObsoleteEntities", required = false, defaultValue = "false")
+            @Parameter(name = "includeObsoleteEntities",
+                    description = "A boolean parameter to specify if obsolete entities should be included or not. Default value is false.") boolean includeObsoleteEntities,
+            @RequestParam
+            @Parameter(name="searchProperties",
+                    description = "Specify any other search field here which are not specified by searchFields or boostFields.") MultiValueMap<String,String> searchProperties
     ) throws ResourceNotFoundException, IOException {
 
 	Map<String, Collection<String>> properties = new HashMap<>();
@@ -65,14 +87,39 @@ public HttpEntity<V2PagedAndFacetedResponse<V2Entity>> getClasses(
     @RequestMapping(path = "/ontologies/{onto}/classes", produces = {MediaType.APPLICATION_JSON_VALUE}, method = RequestMethod.GET)
     public HttpEntity<V2PagedAndFacetedResponse<V2Entity>> getClasses(
             @PageableDefault(size = 20, page = 0) Pageable pageable,
-            @PathVariable("onto") @NotNull String ontologyId,
+            @PathVariable("onto") @NotNull
+            @Parameter(name = "onto",
+                    description = "Ontology Id to get the information about.",
+                    example = "efo") String ontologyId,
             @RequestParam(value = "lang", required = false, defaultValue = "en") String lang,
-            @RequestParam(value = "search", required = false) String search,
-            @RequestParam(value = "searchFields", required = false) String searchFields,
-            @RequestParam(value = "boostFields", required = false) String boostFields,
-            @RequestParam(value = "exactMatch", required = false, defaultValue = "false") boolean exactMatch,
-            @RequestParam(value = "includeObsoleteEntities", required = false, defaultValue = "false") boolean includeObsoleteEntities,
-            @RequestParam MultiValueMap<String,String> searchProperties
+            @RequestParam(value = "search", required = false)
+            @Parameter(name="search",
+                    description = "This parameter specify the search query text.",
+                    example = "liver disease") String search,
+            @RequestParam(value = "searchFields", required = false)
+            @Parameter(name = "searchFields",
+                    description = "This parameter is a white space separated list of fields to search in. " +
+                            "The fields are weighted equally. The fields are defined in the schema. " +
+                            "The default fields are label and definition. " +
+                            "The fields weights can be boosted by appending a caret ^ and a positive integer to the field name. " +
+                            "For example, label^3 synonyms^2 description^1 logical_definition^1",
+                    example = "label^100 description") String searchFields,
+            @RequestParam(value = "boostFields", required = false)
+            @Parameter(name = "boostFields",
+                    description = "This parameter is a white space separated list of fields appended with a caret to boost in search. " +
+                            "The default fields are type, is_defining_ontology, label, curie, shortForm and synonym . " +
+                            "The fields weights can be boosted by appending a caret ^ and a positive integer to the field name. ",
+                    example = "label^100 curie^50") String boostFields,
+            @RequestParam(value = "exactMatch", required = false, defaultValue = "false")
+            @Parameter(name = "exactMatch",
+                    description = "As the name suggests its a boolean parameter to specify if search should be exact match or not." +
+                            "The default value is false") boolean exactMatch,
+            @RequestParam(value = "includeObsoleteEntities", required = false, defaultValue = "false")
+            @Parameter(name = "includeObsoleteEntities",
+                    description = "A boolean parameter to specify if obsolete entities should be included or not. Default value is false.") boolean includeObsoleteEntities,
+            @RequestParam
+            @Parameter(name="searchProperties",
+                    description = "Specify any other search field here which are not specified by searchFields or boostFields.") MultiValueMap<String,String> searchProperties
     ) throws ResourceNotFoundException, IOException {
 
         Map<String,Collection<String>> properties = new HashMap<>();
@@ -89,8 +136,14 @@ public HttpEntity<V2PagedAndFacetedResponse<V2Entity>> getClasses(
 
     @RequestMapping(path = "/ontologies/{onto}/classes/{class}", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET)
     public HttpEntity<V2Entity> getClass(
-            @PathVariable("onto") String ontologyId,
-            @PathVariable("class") String iri,
+            @PathVariable("onto")
+            @Parameter(name = "onto",
+                    description = "Ontology Id to get the information about.",
+                    example = "efo") String ontologyId,
+            @PathVariable("class")
+            @Parameter(name = "class",
+                    description = "The IRI of the class, this value must be double URL encoded",
+                    example = "http%3A%2F%2Fwww.ebi.ac.uk%2Fefo%2FEFO_1000967") String iri,
             @RequestParam(value = "lang", required = false, defaultValue = "en") String lang
     ) throws ResourceNotFoundException {
 
@@ -104,8 +157,14 @@ public HttpEntity<V2Entity> getClass(
     @RequestMapping(path = "/ontologies/{onto}/classes/{class}/children", produces = {MediaType.APPLICATION_JSON_VALUE}, method = RequestMethod.GET)
     public HttpEntity<V2PagedResponse<V2Entity>> getChildrenByOntology(
             @PageableDefault(size = 20, page = 0) Pageable pageable,
-            @PathVariable("onto") String ontologyId,
-            @PathVariable("class") String iri,
+            @PathVariable("onto")
+            @Parameter(name = "onto",
+                    description = "Ontology Id to get the information about.",
+                    example = "efo") String ontologyId,
+            @PathVariable("class")
+            @Parameter(name = "class",
+                    description = "The IRI of the class, this value must be double URL encoded",
+                    example = "http%3A%2F%2Fwww.ebi.ac.uk%2Fefo%2FEFO_1000967") String iri,
             @RequestParam(value = "lang", required = false, defaultValue = "en") String lang
     ) throws ResourceNotFoundException {
 
@@ -121,8 +180,14 @@ public HttpEntity<V2PagedResponse<V2Entity>> getChildrenByOntology(
     @RequestMapping(path = "/ontologies/{onto}/classes/{class}/ancestors", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET)
     public HttpEntity<V2PagedResponse<V2Entity>> getAncestorsByOntology(
             @PageableDefault(size = 20, page = 0) Pageable pageable,
-            @PathVariable("onto") String ontologyId,
-            @PathVariable("class") String iri,
+            @PathVariable("onto")
+            @Parameter(name = "onto",
+                    description = "Ontology Id to get the information about.",
+                    example = "efo") String ontologyId,
+            @PathVariable("class")
+            @Parameter(name = "class",
+                    description = "The IRI of the class, this value must be double URL encoded",
+                    example = "http%3A%2F%2Fwww.ebi.ac.uk%2Fefo%2FEFO_1000967") String iri,
             @RequestParam(value = "lang", required = false, defaultValue = "en") String lang
     ) throws ResourceNotFoundException {
 
@@ -139,8 +204,14 @@ public HttpEntity<V2PagedResponse<V2Entity>> getAncestorsByOntology(
     @RequestMapping(path = "/ontologies/{onto}/classes/{class}/hierarchicalChildren", produces = {MediaType.APPLICATION_JSON_VALUE}, method = RequestMethod.GET)
     public HttpEntity<V2PagedResponse<V2Entity>> getHierarchicalChildrenByOntology(
             @PageableDefault(size = 20, page = 0) Pageable pageable,
-            @PathVariable("onto") String ontologyId,
-            @PathVariable("class") String iri,
+            @PathVariable("onto")
+            @Parameter(name = "onto",
+                    description = "Ontology Id to get the information about.",
+                    example = "efo") String ontologyId,
+            @PathVariable("class")
+            @Parameter(name = "class",
+                    description = "The IRI of the class, this value must be double URL encoded",
+                    example = "http%3A%2F%2Fwww.ebi.ac.uk%2Fefo%2FEFO_1000967") String iri,
             @RequestParam(value = "lang", required = false, defaultValue = "en") String lang
     ) throws ResourceNotFoundException {
 
@@ -156,8 +227,14 @@ public HttpEntity<V2PagedResponse<V2Entity>> getHierarchicalChildrenByOntology(
     @RequestMapping(path = "/ontologies/{onto}/classes/{class}/hierarchicalAncestors", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET)
     public HttpEntity<V2PagedResponse<V2Entity>> getHierarchicalAncestorsByOntology(
             @PageableDefault(size = 20, page = 0) Pageable pageable,
-            @PathVariable("onto") String ontologyId,
-            @PathVariable("class") String iri,
+            @PathVariable("onto")
+            @Parameter(name = "onto",
+                    description = "Ontology Id to get the information about.",
+                    example = "efo") String ontologyId,
+            @PathVariable("class")
+            @Parameter(name = "class",
+                    description = "The IRI of the class, this value must be double URL encoded",
+                    example = "http%3A%2F%2Fwww.ebi.ac.uk%2Fefo%2FEFO_1000967") String iri,
             @RequestParam(value = "lang", required = false, defaultValue = "en") String lang
     ) throws ResourceNotFoundException {
 
@@ -178,8 +255,14 @@ public HttpEntity<V2PagedResponse<V2Entity>> getHierarchicalAncestorsByOntology(
     @RequestMapping(path = "/ontologies/{onto}/individuals/{individual}/ancestors", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET)
     public HttpEntity<V2PagedResponse<V2Entity>> getIndividualAncestorsByOntology(
             @PageableDefault(size = 20, page = 0) Pageable pageable,
-            @PathVariable("onto") String ontologyId,
-            @PathVariable("individual") String iri,
+            @PathVariable("onto")
+            @Parameter(name = "onto",
+                    description = "Ontology Id to get the information about.",
+                    example = "efo") String ontologyId,
+            @PathVariable("individual")
+            @Parameter(name = "individual",
+                    description = "The IRI of the individual, this value must be double URL encoded",
+                    example = "http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FIAO_0000002") String iri,
             @RequestParam(value = "lang", required = false, defaultValue = "en") String lang
     ) throws ResourceNotFoundException {
 

backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2DefinedFieldsController.java

@@ -0,0 +1,56 @@
+package uk.ac.ebi.spot.ols.controller.api.v2;
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+import uk.ac.ebi.ols.shared.DefinedFields;
+
+import java.util.List;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+@RestController
+public class V2DefinedFieldsController {
+
+    @GetMapping("/api/v2/defined-fields")
+    public List<DefinedFieldDto> getDefinedFields() {
+        return Stream.of(DefinedFields.values())
+                .map(field -> new DefinedFieldDto(
+                        field.getText(),
+                        field.getOls3Text(),
+                        field.getDescription(),
+                        field.getType()
+                ))
+                .collect(Collectors.toList());
+    }
+
+    // DTO class for serialization
+    static class DefinedFieldDto {
+        private String ols4FieldName;
+        private String ols3FieldName;
+        private String description;
+        private String dataType;
+
+        public DefinedFieldDto(String ols4FieldName, String ols3FieldName, String description, String dataType) {
+            this.ols4FieldName = ols4FieldName;
+            this.ols3FieldName = ols3FieldName;
+            this.description = description;
+            this.dataType = dataType;
+        }
+
+        public String getOls4FieldName() {
+            return ols4FieldName;
+        }
+
+        public String getOls3FieldName() {
+            return ols3FieldName;
+        }
+
+        public String getDescription() {
+            return description;
+        }
+
+        public String getDataType() {
+            return dataType;
+        }
+    }
+}