Skip to content

Commit

Permalink
Add Swagger Documentation for V2 API
Browse files Browse the repository at this point in the history
  • Loading branch information
@haideriqbal
haideriqbal committed Jan 9, 2025
1 parent 7dde027 commit 17017ee
Show file tree
Hide file tree
Showing 6 changed files with 400 additions and 109 deletions.
143 changes: 113 additions & 30 deletions backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2ClassController.java
View file
Original file line number Diff line number Diff line change
@@ -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;
Expand All @@ -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;
Expand All @@ -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 {

Expand All @@ -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<>();
Expand All @@ -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<>();
Expand All @@ -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 {

Expand All @@ -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 {

Expand All @@ -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 {

Expand All @@ -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 {

Expand All @@ -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 {

Expand All @@ -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 {

Expand Down
Loading

0 comments on commit 17017ee

Please sign in to comment.