From 17017eeea1b0a3f9f142f0973d38a8ac39121a65 Mon Sep 17 00:00:00 2001 From: haider Date: Thu, 9 Jan 2025 13:40:47 +0000 Subject: [PATCH] Add Swagger Documentation for V2 API --- .../controller/api/v2/V2ClassController.java | 143 ++++++++++++++---- .../controller/api/v2/V2EntityController.java | 101 ++++++++++--- .../api/v2/V2IndividualController.java | 103 ++++++++++--- .../api/v2/V2OntologyController.java | 49 ++++-- .../api/v2/V2PropertyController.java | 107 ++++++++++--- .../api/v2/V2StatisticsController.java | 6 +- 6 files changed, 400 insertions(+), 109 deletions(-) diff --git a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2ClassController.java b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2ClassController.java index 4c40859bc..48c975597 100644 --- a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2ClassController.java +++ b/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> 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 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 searchProperties ) throws ResourceNotFoundException, IOException { Map> properties = new HashMap<>(); @@ -65,14 +87,39 @@ public HttpEntity> getClasses( @RequestMapping(path = "/ontologies/{onto}/classes", produces = {MediaType.APPLICATION_JSON_VALUE}, method = RequestMethod.GET) public HttpEntity> 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 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 searchProperties ) throws ResourceNotFoundException, IOException { Map> properties = new HashMap<>(); @@ -89,8 +136,14 @@ public HttpEntity> getClasses( @RequestMapping(path = "/ontologies/{onto}/classes/{class}", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET) public HttpEntity 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 getClass( @RequestMapping(path = "/ontologies/{onto}/classes/{class}/children", produces = {MediaType.APPLICATION_JSON_VALUE}, method = RequestMethod.GET) public HttpEntity> 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> getChildrenByOntology( @RequestMapping(path = "/ontologies/{onto}/classes/{class}/ancestors", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET) public HttpEntity> 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> getAncestorsByOntology( @RequestMapping(path = "/ontologies/{onto}/classes/{class}/hierarchicalChildren", produces = {MediaType.APPLICATION_JSON_VALUE}, method = RequestMethod.GET) public HttpEntity> 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> getHierarchicalChildrenByOntology( @RequestMapping(path = "/ontologies/{onto}/classes/{class}/hierarchicalAncestors", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET) public HttpEntity> 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> getHierarchicalAncestorsByOntology( @RequestMapping(path = "/ontologies/{onto}/individuals/{individual}/ancestors", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET) public HttpEntity> 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 { diff --git a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2EntityController.java b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2EntityController.java index 764520710..b025c4ce7 100644 --- a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2EntityController.java +++ b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2EntityController.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; @@ -29,7 +28,8 @@ import static uk.ac.ebi.ols.shared.DefinedFields.*; -@Controller +@Tag(name = "V2 Entity Controller", description = "This endpoint provides access to entity information.") +@RestController @RequestMapping("/api/v2") public class V2EntityController { @@ -40,13 +40,37 @@ public class V2EntityController { public HttpEntity> getEntities( @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 = "facetFields", required = false) String facetFields, - @RequestParam(value = "exactMatch", required = false, defaultValue = "false") boolean exactMatch, - @RequestParam(value = "includeObsoleteEntities", required = false, defaultValue = "false") boolean includeObsoleteEntities, - @RequestParam MultiValueMap 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 = "facetFields", required = false) + @Parameter(name = "facetFields", + description = "This parameter is a white space separated list of fields to facet data by.") String facetFields, + @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 searchProperties ) throws ResourceNotFoundException, IOException { Map> properties = new HashMap<>(); @@ -64,15 +88,42 @@ public HttpEntity> getEntities( @RequestMapping(path = "/ontologies/{onto}/entities", produces = {MediaType.APPLICATION_JSON_VALUE}, method = RequestMethod.GET) public HttpEntity> getTerms( @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 = "facetFields", required = false) String facetFields, - @RequestParam(value = "exactMatch", required = false, defaultValue = "false") boolean exactMatch, - @RequestParam(value = "includeObsoleteEntities", required = false, defaultValue = "false") boolean includeObsoleteEntities, - @RequestParam MultiValueMap 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 = "facetFields", required = false) + @Parameter(name = "facetFields", + description = "This parameter is a white space separated list of fields to facet data by.") String facetFields, + @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 searchProperties ) throws ResourceNotFoundException, IOException { Map> properties = new HashMap<>(); @@ -89,8 +140,14 @@ public HttpEntity> getTerms( @RequestMapping(path = "/ontologies/{onto}/entities/{entity}", produces = {MediaType.APPLICATION_JSON_VALUE}, method = RequestMethod.GET) public HttpEntity getEntity( - @PathVariable("onto") String ontologyId, - @PathVariable("entity") String iri, + @PathVariable("onto") + @Parameter(name = "onto", + description = "Ontology Id to get the information about.", + example = "efo") String ontologyId, + @PathVariable("entity") + @Parameter(name = "entity", + description = "The IRI of the entity, 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 { diff --git a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2IndividualController.java b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2IndividualController.java index 00feeb842..5a45f9320 100644 --- a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2IndividualController.java +++ b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2IndividualController.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; @@ -11,10 +13,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 java.util.List; import java.util.Map; -@Controller +@Tag(name = "V2 Individual Controller", description = "This endpoint provides access to individuals information.") +@RestController @RequestMapping("/api/v2") public class V2IndividualController { @@ -41,12 +41,34 @@ public class V2IndividualController { public HttpEntity> getIndividuals( @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 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 searchProperties ) throws ResourceNotFoundException, IOException { Map> properties = new HashMap<>(); @@ -64,14 +86,39 @@ public HttpEntity> getIndividuals( @RequestMapping(path = "/ontologies/{onto}/individuals", produces = {MediaType.APPLICATION_JSON_VALUE, MediaTypes.HAL_JSON_VALUE}, method = RequestMethod.GET) public HttpEntity> getIndividuals( @PageableDefault(size = 20, page = 0) Pageable pageable, - @PathVariable("onto") @NotNull String ontologyId, + @PathVariable("onto") @NotNull + @Parameter(name = "onto", + description = "Ontology Id to search individuals in.", + 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 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 searchProperties ) throws ResourceNotFoundException, IOException { Map> properties = new HashMap<>(); @@ -88,8 +135,14 @@ public HttpEntity> getIndividuals( @RequestMapping(path = "/ontologies/{onto}/individuals/{individual}", produces = {MediaType.APPLICATION_JSON_VALUE, MediaTypes.HAL_JSON_VALUE}, method = RequestMethod.GET) public HttpEntity getIndividual( - @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 { @@ -104,8 +157,14 @@ public HttpEntity getIndividual( @RequestMapping(path = "/ontologies/{onto}/classes/{class}/individuals", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET) public HttpEntity> getClassIndividuals( @PageableDefault(size = 20, page = 0) Pageable pageable, - @PathVariable("onto") String ontologyId, - @PathVariable("class") String classIri, + @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 classIri, @RequestParam(value = "lang", required = false, defaultValue = "en") String lang ) throws ResourceNotFoundException, IOException { diff --git a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2OntologyController.java b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2OntologyController.java index d84c8a82d..b032722b7 100644 --- a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2OntologyController.java +++ b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2OntologyController.java @@ -1,6 +1,8 @@ package uk.ac.ebi.spot.ols.controller.api.v2; import com.google.gson.Gson; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.tags.Tag; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Autowired; @@ -12,10 +14,7 @@ import org.springframework.http.MediaType; import org.springframework.http.ResponseEntity; import org.springframework.stereotype.Controller; -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 uk.ac.ebi.spot.ols.controller.api.v2.helpers.DynamicQueryHelper; import uk.ac.ebi.spot.ols.controller.api.v2.responses.V2PagedAndFacetedResponse; import uk.ac.ebi.spot.ols.model.v2.V2Entity; @@ -28,7 +27,8 @@ import java.util.List; import java.util.Map; -@Controller +@Tag(name = "V2 Ontology Controller", description = "This endpoint provides access to ontology information.") +@RestController @RequestMapping("/api/v2/ontologies") public class V2OntologyController { @@ -43,12 +43,34 @@ public class V2OntologyController { public HttpEntity> getOntologies( @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 Map> 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.") Map> searchProperties ) throws ResourceNotFoundException, IOException { Map> properties = new HashMap<>(); @@ -65,7 +87,10 @@ public HttpEntity> getOntologies( @RequestMapping(path = "/{onto}", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET) public HttpEntity getOntology( - @PathVariable("onto") String ontologyId, + @PathVariable("onto") + @Parameter(name = "onto", + description = "Ontology Id to get the information about.", + example = "efo") String ontologyId, @RequestParam(value = "lang", required = false, defaultValue = "en") String lang ) throws ResourceNotFoundException { logger.trace("ontologyId = {}, lang = {}", ontologyId, lang); diff --git a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2PropertyController.java b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2PropertyController.java index b613fc0dc..0efb250af 100644 --- a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2PropertyController.java +++ b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2PropertyController.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; @@ -8,7 +10,6 @@ import org.springframework.http.HttpStatus; import org.springframework.http.MediaType; import org.springframework.http.ResponseEntity; -import org.springframework.stereotype.Controller; import org.springframework.util.MultiValueMap; import org.springframework.web.bind.annotation.*; import org.springframework.web.util.UriUtils; @@ -28,7 +29,8 @@ import java.util.List; import java.util.Map; -@Controller +@Tag(name = "V2 Property Controller", description = "This endpoint provides access to property information.") +@RestController @RequestMapping("/api/v2") public class V2PropertyController { @@ -39,12 +41,33 @@ public class V2PropertyController { public HttpEntity> getProperties( @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 Map> 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.") Map> searchProperties ) throws ResourceNotFoundException, IOException { Map> properties = new HashMap<>(); @@ -62,14 +85,38 @@ public HttpEntity> getProperties( @RequestMapping(path = "/ontologies/{onto}/properties", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET) public HttpEntity> getProperties( @PageableDefault(size = 20, page = 0) Pageable pageable, - @PathVariable("onto") @NotNull String ontologyId, + @PathVariable("onto") @NotNull + @Parameter(name = "onto", + description = "Ontology Id to search properties in.", + 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 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 = "search fields", + 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 = "boost fields", + 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="search properties", description = "Specify any other search field here which are not specified by searchFields or boostFields.") MultiValueMap searchProperties ) throws ResourceNotFoundException, IOException { Map> properties = new HashMap<>(); @@ -86,8 +133,14 @@ public HttpEntity> getProperties( @RequestMapping(path = "/ontologies/{onto}/properties/{property}", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET) public HttpEntity getProperty( - @PathVariable("onto") String ontologyId, - @PathVariable("property") String iri, + @PathVariable("onto") + @Parameter(name = "onto", + description = "Ontology Id to search properties in.", + example = "efo") String ontologyId, + @PathVariable("property") + @Parameter(name = "property", + description = "The IRI of the property, this value must be double URL encoded", + example = "http%3A%2F%2Fwww.ebi.ac.uk%2Fefo%2FEFO_0000742") String iri, @RequestParam(value = "lang", required = false, defaultValue = "en") String lang ) throws ResourceNotFoundException { @@ -101,8 +154,14 @@ public HttpEntity getProperty( @RequestMapping(path = "/ontologies/{onto}/properties/{property}/children", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET) public HttpEntity> getChildrenByOntology( @PageableDefault(size = 20, page = 0) Pageable pageable, - @PathVariable("onto") String ontologyId, - @PathVariable("property") String iri, + @PathVariable("onto") + @Parameter(name = "onto", + description = "Ontology Id to search properties in.", + example = "efo") String ontologyId, + @PathVariable("property") + @Parameter(name = "property", + description = "The IRI of the property, this value must be double URL encoded", + example = "http%3A%2F%2Fwww.ebi.ac.uk%2Fefo%2FEFO_0000742") String iri, @RequestParam(value = "lang", required = false, defaultValue = "en") String lang ) throws ResourceNotFoundException { @@ -118,8 +177,14 @@ public HttpEntity> getChildrenByOntology( @RequestMapping(path = "/ontologies/{onto}/properties/{property}/ancestors", produces = {MediaType.APPLICATION_JSON_VALUE }, method = RequestMethod.GET) public HttpEntity> getAncestorsByOntology( @PageableDefault(size = 20, page = 0) Pageable pageable, - @PathVariable("onto") String ontologyId, - @PathVariable("property") String iri, + @PathVariable("onto") + @Parameter(name = "onto", + description = "Ontology Id to search properties in.", + example = "efo") String ontologyId, + @PathVariable("property") + @Parameter(name = "property", + description = "The IRI of the property, this value must be double URL encoded", + example = "http%3A%2F%2Fwww.ebi.ac.uk%2Fefo%2FEFO_0000742") String iri, @RequestParam(value = "lang", required = false, defaultValue = "en") String lang ) throws ResourceNotFoundException { diff --git a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2StatisticsController.java b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2StatisticsController.java index 0af7b2460..e210bcbb3 100644 --- a/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2StatisticsController.java +++ b/backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2StatisticsController.java @@ -1,5 +1,6 @@ package uk.ac.ebi.spot.ols.controller.api.v2; +import io.swagger.v3.oas.annotations.tags.Tag; import org.apache.solr.client.solrj.SolrQuery; import org.apache.solr.client.solrj.response.FacetField; import org.apache.solr.client.solrj.response.QueryResponse; @@ -13,14 +14,15 @@ import org.springframework.stereotype.Controller; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; +import org.springframework.web.bind.annotation.RestController; import uk.ac.ebi.spot.ols.model.v2.V2Statistics; import uk.ac.ebi.spot.ols.repository.solr.OlsSolrClient; import java.io.IOException; import java.util.HashMap; import java.util.Map; - -@Controller +@Tag(name = "V2 Stats Controller", description = "This endpoint provides statistics about the current state of the ontology index. It includes the number of ontologies, classes, individuals and properties indexed, and the last time the index was modified.") +@RestController @RequestMapping("/api/v2/stats") public class V2StatisticsController {