Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Swagger Documentation for V2 API #820

Open
wants to merge 1 commit into
base: dev
Choose a base branch
from
Open

Add Swagger Documentation for V2 API #820

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 113 additions & 30 deletions backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2ClassController.java
View file
Open in desktop
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
Loading