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

Merged
merged 5 commits into from
Jan 14, 2025
Merged

Add Swagger Documentation for V2 API #820

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
17017ee
Add Swagger Documentation for V2 API
haideriqbal Jan 9, 2025
febfef3
Add DefinedFields page on frontend
haideriqbal Jan 14, 2025
004f8b5
Update URL format
haideriqbal Jan 14, 2025
fc0d0bc
Remove Extra Slash in URL
haideriqbal Jan 14, 2025
254bfb9
Update URL in SwaggerConfig
haideriqbal Jan 14, 2025
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
4 changes: 2 additions & 2 deletions backend/src/main/java/uk/ac/ebi/spot/ols/config/SwaggerConfig.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
@Configuration
public class SwaggerConfig {

private final String OLS4_SERVER_URL = "https://www.ebi.ac.uk/ols4";
private final String OLS4_SERVER_URL = "https://wwwdev.ebi.ac.uk/ols4";

@Lazy
@Bean
Expand All @@ -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' style='font-weight: bold; font-size: 16px;'>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()
Expand Down
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
56 changes: 56 additions & 0 deletions backend/src/main/java/uk/ac/ebi/spot/ols/controller/api/v2/V2DefinedFieldsController.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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;
}
}
}
Loading
Loading