From 4c530140253315bc74ac2e7080f37c88cee1b348 Mon Sep 17 00:00:00 2001 From: Thomas Georgios Giannos Date: Thu, 4 Jul 2024 17:28:21 +0300 Subject: [PATCH] Added swagger docs for references and their types --- .../controllers/ReferenceController.java | 81 ++- .../controllers/ReferenceTypeController.java | 79 ++- .../controllers/swagger/SwaggerHelpers.java | 493 ++++++++++++++++++ .../web/src/main/resources/config/swagger.yml | 2 +- 4 files changed, 646 insertions(+), 9 deletions(-) diff --git a/backend/web/src/main/java/org/opencdmp/controllers/ReferenceController.java b/backend/web/src/main/java/org/opencdmp/controllers/ReferenceController.java index 403515e62..94707022a 100644 --- a/backend/web/src/main/java/org/opencdmp/controllers/ReferenceController.java +++ b/backend/web/src/main/java/org/opencdmp/controllers/ReferenceController.java @@ -12,14 +12,28 @@ import gr.cite.tools.fieldset.FieldSet; import gr.cite.tools.logging.LoggerService; import gr.cite.tools.logging.MapLogEntry; import gr.cite.tools.validation.ValidationFilterAnnotation; +import io.swagger.v3.oas.annotations.Hidden; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.media.ArraySchema; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.tags.Tag; import jakarta.transaction.Transactional; import jakarta.xml.bind.JAXBException; import org.opencdmp.audit.AuditableAction; import org.opencdmp.authorization.AuthorizationFlags; +import org.opencdmp.controllers.swagger.SwaggerHelpers; +import org.opencdmp.controllers.swagger.annotation.OperationWithTenantHeader; +import org.opencdmp.controllers.swagger.annotation.Swagger400; +import org.opencdmp.controllers.swagger.annotation.Swagger404; +import org.opencdmp.controllers.swagger.annotation.SwaggerCommonErrorResponses; import org.opencdmp.data.ReferenceEntity; import org.opencdmp.model.builder.reference.ReferenceBuilder; import org.opencdmp.model.censorship.reference.ReferenceCensor; import org.opencdmp.model.persist.ReferencePersist; +import org.opencdmp.model.planblueprint.PlanBlueprint; import org.opencdmp.model.reference.Reference; import org.opencdmp.model.result.QueryResult; import org.opencdmp.query.ReferenceQuery; @@ -42,6 +56,8 @@ import java.util.UUID; @RestController @RequestMapping(path = "api/reference") +@Tag(name = "References", description = "Manage references") +@SwaggerCommonErrorResponses public class ReferenceController { private static final LoggerService logger = new LoggerService(LoggerFactory.getLogger(ReferenceController.class)); @@ -76,6 +92,25 @@ public class ReferenceController { } @PostMapping("query") + @OperationWithTenantHeader(summary = "Query all references", description = SwaggerHelpers.Reference.endpoint_query, requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(description = SwaggerHelpers.Reference.endpoint_query_request_body, content = @Content( + examples = { + @ExampleObject( + name = "Pagination and projection", + description = "Simple paginated request using a property projection list and pagination info", + value = SwaggerHelpers.Reference.endpoint_query_request_body_example + ) + } + )), responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + array = @ArraySchema( + schema = @Schema( + implementation = Reference.class + ) + ), + examples = @ExampleObject( + name = "First page", + description = "Example with the first page of paginated results", + value = SwaggerHelpers.Reference.endpoint_query_response_example + )))) public QueryResult query(@RequestBody ReferenceLookup lookup) throws MyApplicationException, MyForbiddenException { logger.debug("querying {}", Reference.class.getSimpleName()); @@ -93,6 +128,8 @@ public class ReferenceController { @PostMapping("search") + @Hidden + //TODO thgiannos add swagger docs public List searchReferenceWithDefinition(@RequestBody ReferenceSearchLookup lookup) throws MyNotFoundException, InvalidApplicationException { logger.debug("search with db definition {}", Reference.class.getSimpleName()); @@ -106,7 +143,17 @@ public class ReferenceController { } @GetMapping("find/{referenceTypeId}") - public Boolean findReference(@PathVariable("referenceTypeId") UUID referenceTypeId, @RequestParam("reference") String reference) throws MyNotFoundException { + @OperationWithTenantHeader(summary = "Fetch a specific reference by type id and reference value", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = Boolean.class + )) + )) + @Swagger404 + public Boolean findReference( + @Parameter(name = "referenceTypeId", description = "The type id of a reference to check if it exists", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("referenceTypeId") UUID referenceTypeId, + @Parameter(name = "reference", description = "The reference value of a reference to check if it exists", example = "MIT Licence", required = true) @RequestParam("reference") String reference + ) throws MyNotFoundException { logger.debug("search with db definition {}", Reference.class.getSimpleName()); this.censorFactory.censor(ReferenceCensor.class).censor(null, null); @@ -119,7 +166,17 @@ public class ReferenceController { } @GetMapping("{id}") - public Reference get(@PathVariable("id") UUID id, FieldSet fieldSet) throws MyApplicationException, MyForbiddenException, MyNotFoundException { + @OperationWithTenantHeader(summary = "Fetch a specific reference by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = Reference.class + )) + )) + @Swagger404 + public Reference get( + @Parameter(name = "id", description = "The id of a reference to fetch", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id, + @Parameter(name = "fieldSet", description = SwaggerHelpers.Commons.fieldset_description, required = true) FieldSet fieldSet + ) throws MyApplicationException, MyForbiddenException, MyNotFoundException { logger.debug(new MapLogEntry("retrieving" + Reference.class.getSimpleName()).And("id", id).And("fields", fieldSet)); this.censorFactory.censor(ReferenceCensor.class).censor(fieldSet, null); @@ -138,9 +195,20 @@ public class ReferenceController { } @PostMapping("persist") + @OperationWithTenantHeader(summary = "Create a new or update an existing reference", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = Reference.class + )) + )) + @Swagger400 + @Swagger404 @Transactional @ValidationFilterAnnotation(validator = ReferencePersist.ReferencePersistValidator.ValidatorName, argumentName = "model") - public Reference persist(@RequestBody ReferencePersist model, FieldSet fieldSet) throws MyApplicationException, MyForbiddenException, MyNotFoundException, InvalidApplicationException, JAXBException, ParserConfigurationException, JsonProcessingException, TransformerException { + public Reference persist( + @RequestBody ReferencePersist model, + @Parameter(name = "fieldSet", description = SwaggerHelpers.Commons.fieldset_description, required = true) FieldSet fieldSet + ) throws MyApplicationException, MyForbiddenException, MyNotFoundException, InvalidApplicationException, JAXBException, ParserConfigurationException, JsonProcessingException, TransformerException { logger.debug(new MapLogEntry("persisting" + Reference.class.getSimpleName()).And("model", model).And("fieldSet", fieldSet)); this.censorFactory.censor(ReferenceCensor.class).censor(fieldSet, null); @@ -155,8 +223,13 @@ public class ReferenceController { } @DeleteMapping("{id}") + @OperationWithTenantHeader(summary = "Delete a reference by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) + @Swagger404 @Transactional - public void delete(@PathVariable("id") UUID id) throws MyForbiddenException, InvalidApplicationException { + public void delete( + @Parameter(name = "id", description = "The id of a reference to delete", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id + ) throws MyForbiddenException, InvalidApplicationException { logger.debug(new MapLogEntry("retrieving" + Reference.class.getSimpleName()).And("id", id)); this.referenceService.deleteAndSave(id); diff --git a/backend/web/src/main/java/org/opencdmp/controllers/ReferenceTypeController.java b/backend/web/src/main/java/org/opencdmp/controllers/ReferenceTypeController.java index 78c430869..6c500aac8 100644 --- a/backend/web/src/main/java/org/opencdmp/controllers/ReferenceTypeController.java +++ b/backend/web/src/main/java/org/opencdmp/controllers/ReferenceTypeController.java @@ -13,14 +13,28 @@ import gr.cite.tools.fieldset.FieldSet; import gr.cite.tools.logging.LoggerService; import gr.cite.tools.logging.MapLogEntry; import gr.cite.tools.validation.ValidationFilterAnnotation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.media.ArraySchema; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.tags.Tag; import jakarta.transaction.Transactional; import jakarta.xml.bind.JAXBException; import org.opencdmp.audit.AuditableAction; import org.opencdmp.authorization.AuthorizationFlags; +import org.opencdmp.controllers.swagger.SwaggerHelpers; +import org.opencdmp.controllers.swagger.annotation.OperationWithTenantHeader; +import org.opencdmp.controllers.swagger.annotation.Swagger400; +import org.opencdmp.controllers.swagger.annotation.Swagger404; +import org.opencdmp.controllers.swagger.annotation.SwaggerCommonErrorResponses; import org.opencdmp.data.ReferenceTypeEntity; import org.opencdmp.model.builder.referencetype.ReferenceTypeBuilder; import org.opencdmp.model.censorship.referencetype.ReferenceTypeCensor; import org.opencdmp.model.persist.ReferenceTypePersist; +import org.opencdmp.model.planblueprint.PlanBlueprint; +import org.opencdmp.model.reference.Reference; import org.opencdmp.model.referencetype.ReferenceType; import org.opencdmp.model.result.QueryResult; import org.opencdmp.query.ReferenceTypeQuery; @@ -40,6 +54,8 @@ import java.util.UUID; @RestController @RequestMapping(path = "api/reference-type") +@Tag(name = "Reference types", description = "Manage reference types") +@SwaggerCommonErrorResponses public class ReferenceTypeController{ private static final LoggerService logger = new LoggerService(LoggerFactory.getLogger(ReferenceTypeController.class)); @@ -75,6 +91,25 @@ public class ReferenceTypeController{ } @PostMapping("query") + @OperationWithTenantHeader(summary = "Query all reference types", description = SwaggerHelpers.ReferenceType.endpoint_query, requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(description = SwaggerHelpers.ReferenceType.endpoint_query_request_body, content = @Content( + examples = { + @ExampleObject( + name = "Pagination and projection", + description = "Simple paginated request using a property projection list and pagination info", + value = SwaggerHelpers.ReferenceType.endpoint_query_request_body_example + ) + } + )), responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + array = @ArraySchema( + schema = @Schema( + implementation = ReferenceType.class + ) + ), + examples = @ExampleObject( + name = "First page", + description = "Example with the first page of paginated results", + value = SwaggerHelpers.ReferenceType.endpoint_query_response_example + )))) public QueryResult query(@RequestBody ReferenceTypeLookup lookup) throws MyApplicationException, MyForbiddenException { logger.debug("querying {}", ReferenceType.class.getSimpleName()); @@ -91,7 +126,17 @@ public class ReferenceTypeController{ } @GetMapping("{id}") - public ReferenceType get(@PathVariable("id") UUID id, FieldSet fieldSet) throws MyApplicationException, MyForbiddenException, MyNotFoundException { + @OperationWithTenantHeader(summary = "Fetch a specific reference type by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = ReferenceType.class + )) + )) + @Swagger404 + public ReferenceType get( + @Parameter(name = "id", description = "The id of a reference type to fetch", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id, + @Parameter(name = "fieldSet", description = SwaggerHelpers.Commons.fieldset_description, required = true) FieldSet fieldSet + ) throws MyApplicationException, MyForbiddenException, MyNotFoundException { logger.debug(new MapLogEntry("retrieving" + ReferenceType.class.getSimpleName()).And("id", id).And("fields", fieldSet)); this.censorFactory.censor(ReferenceTypeCensor.class).censor(fieldSet, null); @@ -110,7 +155,17 @@ public class ReferenceTypeController{ } @GetMapping("code/{code}") - public ReferenceType get(@PathVariable("code") String code, FieldSet fieldSet) throws MyApplicationException, MyForbiddenException, MyNotFoundException { + @OperationWithTenantHeader(summary = "Fetch a specific reference type by code", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = ReferenceType.class + )) + )) + @Swagger404 + public ReferenceType get( + @Parameter(name = "code", description = "The code of a reference type to fetch", example = "licences", required = true) @PathVariable("code") String code, + @Parameter(name = "fieldSet", description = SwaggerHelpers.Commons.fieldset_description, required = true) FieldSet fieldSet + ) throws MyApplicationException, MyForbiddenException, MyNotFoundException { logger.debug(new MapLogEntry("retrieving" + ReferenceType.class.getSimpleName()).And("code", code).And("fields", fieldSet)); this.censorFactory.censor(ReferenceTypeCensor.class).censor(fieldSet, null); @@ -129,9 +184,20 @@ public class ReferenceTypeController{ } @PostMapping("persist") + @OperationWithTenantHeader(summary = "Create a new or update an existing reference type", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = ReferenceType.class + )) + )) + @Swagger400 + @Swagger404 @Transactional @ValidationFilterAnnotation(validator = ReferenceTypePersist.ReferenceTypePersistValidator.ValidatorName, argumentName = "model") - public ReferenceType persist(@RequestBody ReferenceTypePersist model, FieldSet fieldSet) throws MyApplicationException, MyForbiddenException, MyNotFoundException, InvalidApplicationException, JAXBException, JsonProcessingException, InvalidApplicationException { + public ReferenceType persist( + @RequestBody ReferenceTypePersist model, + @Parameter(name = "fieldSet", description = SwaggerHelpers.Commons.fieldset_description, required = true) FieldSet fieldSet + ) throws MyApplicationException, MyForbiddenException, MyNotFoundException, InvalidApplicationException, JAXBException, JsonProcessingException, InvalidApplicationException { logger.debug(new MapLogEntry("persisting" + ReferenceType.class.getSimpleName()).And("model", model).And("fieldSet", fieldSet)); this.censorFactory.censor(ReferenceTypeCensor.class).censor(fieldSet, null); @@ -146,8 +212,13 @@ public class ReferenceTypeController{ } @DeleteMapping("{id}") + @OperationWithTenantHeader(summary = "Delete a plan blueprint by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) + @Swagger404 @Transactional - public void delete(@PathVariable("id") UUID id) throws MyForbiddenException, InvalidApplicationException { + public void delete( + @Parameter(name = "id", description = "The id of a reference type to delete", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id + ) throws MyForbiddenException, InvalidApplicationException { logger.debug(new MapLogEntry("retrieving" + ReferenceType.class.getSimpleName()).And("id", id)); this.referenceTypeService.deleteAndSave(id); diff --git a/backend/web/src/main/java/org/opencdmp/controllers/swagger/SwaggerHelpers.java b/backend/web/src/main/java/org/opencdmp/controllers/swagger/SwaggerHelpers.java index 20cea798b..f67d7bbcc 100644 --- a/backend/web/src/main/java/org/opencdmp/controllers/swagger/SwaggerHelpers.java +++ b/backend/web/src/main/java/org/opencdmp/controllers/swagger/SwaggerHelpers.java @@ -3086,4 +3086,497 @@ public class SwaggerHelpers { } + public static class Reference { + + public static final String endpoint_query = + """ + This endpoint is used to fetch all the available references.
+ It also allows to restrict the results using a query object passed in the request body.
+ """; + + public static final String endpoint_query_request_body = + """ + Let's explore the options this object gives us. + + ### General query parameters: + +
    +
  • page: + This is an object controlling the pagination of the results. It contains two properties. +
    • +
      +
    • offset: + How many records to omit. +
      • +
    • size: + How many records to include in each page. +
      • +
    +
+ + For example, if we want the third page, and our pages to contain 15 elements, we would pass the following object: + + ```JSON + { + "offset": 30, + "size": 15 + } + ``` + +
    +
  • order: + This is an object controlling the ordering of the results. + It contains a list of strings called items with the names of the properties to use. +
    If the name of the property is prefixed with a '-', the ordering direction is DESC. Otherwise, it is ASC. +
    • +
+ + For example, if we wanted to order based on the field 'createdAt' in descending order, we would pass the following object: + + ```JSON + { + "items": [ + "-createdAt" + ], + } + ``` + +
    +
  • metadata: + This is an object containing metadata for the request. There is only one available option. +
      +
    • countAll: + If this is set to true, the count property included in the response will account for all the records regardless the pagination, + with all the rest of filtering options applied of course. + Otherwise, if it is set to false or not present, only the returned results will be counted. +
      The first option is useful for the UI clients to calculate how many result pages are available. +
      • +
    +
    • +
  • project: + This is an object controlling the data projection of the results. + It contains a list of strings called fields with the names of the properties to project. +
    You can also include properties that are deeper in the object tree by prefixing them with dots. +
    • +
+ + ### Reference specific query parameters: + +
    +
  • like: + If there is a like parameter present in the query, only the reference entities that include the contents of the parameter either in their labels, descriptions or the references will be in the response. +
    • +
  • ids: + This is a list and contains the ids we want to include in the response.
    If empty, every record is included. +
    • +
  • excludedIds: + This is a list and contains the ids we want to exclude from the response.
    If empty, no record gets excluded. +
    • +
  • typeIds: + This is a list and contains the ids of the types of the references we want to include in the response.
    If empty, every record is included. +
    • +
  • isActive: + This is a list and determines which records we want to include in the response, based on if they are deleted or not. + This filter works like this. If we want to view only the active records we pass [1] and for only the deleted records we pass [0]. +
    If not present or if we pass [0,1], every record is included. +
    • +
  • sourceTypes: + This is a list and determines which records we want to include in the response, based on their resource type. + The resource type can only be Internal or External. We add 0 or 1 to the list respectively. +
    If not present, every record is included. +
    • +
+ """; + + public static final String endpoint_query_request_body_example = + """ + { + "project":{ + "fields":[ + "id", + "label", + "createdAt", + "updatedAt", + "isActive", + "reference", + "abbreviation", + "description", + "source", + "sourceType", + "belongsToCurrentTenant" + ] + }, + "metadata":{ + "countAll":true + }, + "page":{ + "offset":0, + "size":10 + }, + "isActive":[ + 1 + ], + "order":{ + "items":[ + "-createdAt" + ] + } + } + """; + + public static final String endpoint_query_response_example = + """ + { + "items":[ + { + "id":"016eba8f-1029-49cc-87eb-bfe17901d940", + "label":"researcher", + "reference":"12344", + "abbreviation":"", + "source":"Internal", + "sourceType":0, + "isActive":1, + "createdAt":"2024-07-04T12:55:40.330369Z", + "updatedAt":"2024-07-04T12:55:40.332366Z", + "belongsToCurrentTenant":true + }, + { + "id":"6d36fefe-94b4-4fce-9e4c-8f7421fdfd83", + "label":"Grant", + "reference":"grantId", + "abbreviation":"", + "source":"Internal", + "sourceType":0, + "isActive":1, + "createdAt":"2024-07-04T12:54:29.108764Z", + "updatedAt":"2024-07-04T12:54:29.110765Z", + "belongsToCurrentTenant":true + }, + { + "id":"1ad6d13b-1dd6-4189-a915-ba082984d185", + "label":"Funder", + "reference":"funderid", + "abbreviation":"", + "source":"Internal", + "sourceType":0, + "isActive":1, + "createdAt":"2024-07-04T12:54:28.936293Z", + "updatedAt":"2024-07-04T12:54:28.939293Z", + "belongsToCurrentTenant":true + }, + { + "id":"9c4c469c-3a86-405c-b09a-8d830957be75", + "label":"Argentine Peso", + "reference":"ARS", + "source":"currencies", + "sourceType":1, + "isActive":1, + "createdAt":"2024-07-04T12:46:52.939455Z", + "updatedAt":"2024-07-04T12:46:52.941187Z", + "belongsToCurrentTenant":true + }, + { + "id":"7128614f-3f34-4844-9cbf-39bce1e12d7a", + "label":"ADHDgene", + "reference":"fairsharing_::1549", + "source":"openaire", + "sourceType":1, + "isActive":1, + "createdAt":"2024-07-04T12:46:52.723995Z", + "updatedAt":"2024-07-04T12:46:52.726995Z", + "belongsToCurrentTenant":true + }, + { + "id":"3ba9da7d-5745-4686-a3fb-bc3cce4044b2", + "label":"Cite Project", + "reference":"cite_project", + "source":"project", + "sourceType":1, + "isActive":1, + "createdAt":"2024-07-04T12:39:12.784789Z", + "updatedAt":"2024-07-04T12:39:12.786810Z", + "belongsToCurrentTenant":true + }, + { + "id":"84796db1-633d-4de7-af4d-b7fe5fad16c0", + "label":"A Randomized, Double-Blind, Placebo-Controlled, Multi-Center Study to Evaluate the Efficacy of ManNAc in Subjects with GNE Myopathy (nih_________::5U01AR070498-04)", + "reference":"nih_________::5U01AR070498-04", + "source":"openaire", + "sourceType":1, + "isActive":1, + "createdAt":"2024-07-04T12:39:12.564228Z", + "updatedAt":"2024-07-04T12:39:12.567428Z", + "belongsToCurrentTenant":true + }, + { + "id":"067d98cb-c4af-4958-a197-0c248afc9fe9", + "label":"FCT - Fundação para a Ciência e a Teconlogia", + "reference":"//ror.org/00snfqn58", + "source":"openaire", + "sourceType":1, + "isActive":1, + "createdAt":"2024-06-27T13:50:15.644509Z", + "updatedAt":"2024-06-27T13:50:15.644509Z", + "belongsToCurrentTenant":true + }, + { + "id":"8ea35687-229a-4c3b-95ec-b3c92b0963b0", + "label":"BuG@Sbase", + "reference":"fairsharing_::1556", + "source":"openaire", + "sourceType":1, + "isActive":1, + "createdAt":"2024-06-27T13:50:14.273886Z", + "updatedAt":"2024-06-27T13:50:14.273886Z", + "belongsToCurrentTenant":true + }, + { + "id":"503037eb-a2d1-4bb7-aa23-afecebb3fee0", + "label":"Amilya Agustina (orcid:0000-0002-9102-1506)", + "reference":"0000-0002-9102-1506", + "source":"orcid", + "sourceType":1, + "isActive":1, + "createdAt":"2024-06-27T13:50:14.230997Z", + "updatedAt":"2024-06-27T13:50:14.230997Z", + "belongsToCurrentTenant":true + } + ], + "count":14270 + } + """; + + } + + public static class ReferenceType { + + public static final String endpoint_query = + """ + This endpoint is used to fetch all the available reference types.
+ It also allows to restrict the results using a query object passed in the request body.
+ """; + + public static final String endpoint_query_request_body = + """ + Let's explore the options this object gives us. + + ### General query parameters: + +
    +
  • page: + This is an object controlling the pagination of the results. It contains two properties. +
    • +
      +
    • offset: + How many records to omit. +
      • +
    • size: + How many records to include in each page. +
      • +
    +
+ + For example, if we want the third page, and our pages to contain 15 elements, we would pass the following object: + + ```JSON + { + "offset": 30, + "size": 15 + } + ``` + +
    +
  • order: + This is an object controlling the ordering of the results. + It contains a list of strings called items with the names of the properties to use. +
    If the name of the property is prefixed with a '-', the ordering direction is DESC. Otherwise, it is ASC. +
    • +
+ + For example, if we wanted to order based on the field 'createdAt' in descending order, we would pass the following object: + + ```JSON + { + "items": [ + "-createdAt" + ], + } + ``` + +
    +
  • metadata: + This is an object containing metadata for the request. There is only one available option. +
      +
    • countAll: + If this is set to true, the count property included in the response will account for all the records regardless the pagination, + with all the rest of filtering options applied of course. + Otherwise, if it is set to false or not present, only the returned results will be counted. +
      The first option is useful for the UI clients to calculate how many result pages are available. +
      • +
    +
    • +
  • project: + This is an object controlling the data projection of the results. + It contains a list of strings called fields with the names of the properties to project. +
    You can also include properties that are deeper in the object tree by prefixing them with dots. +
    • +
+ + ### Reference type specific query parameters: + +
    +
  • like: + If there is a like parameter present in the query, only the reference entities that include the contents of the parameter either in their names or their codes will be in the response. +
    • +
  • ids: + This is a list and contains the ids we want to include in the response.
    If empty, every record is included. +
    • +
  • excludedIds: + This is a list and contains the ids we want to exclude from the response.
    If empty, no record gets excluded. +
    • +
  • isActive: + This is a list and determines which records we want to include in the response, based on if they are deleted or not. + This filter works like this. If we want to view only the active records we pass [1] and for only the deleted records we pass [0]. +
    If not present or if we pass [0,1], every record is included. +
    • +
  • codes: + This is a list and determines which records we want to include in the response, based on their code. +
    If not present, every record is included. +
    • +
+ """; + + public static final String endpoint_query_request_body_example = + """ + { + "project":{ + "fields":[ + "id", + "name", + "code", + "createdAt", + "updatedAt", + "isActive", + "belongsToCurrentTenant" + ] + }, + "metadata":{ + "countAll":true + }, + "page":{ + "offset":0, + "size":10 + }, + "isActive":[ + 1 + ], + "order":{ + "items":[ + "-createdAt" + ] + } + } + """; + + public static final String endpoint_query_response_example = + """ + { + "items":[ + { + "id":"7f4ea357-27ae-45bb-9588-551f1d926760", + "name":"Select format(s)", + "code":"Select format(s)", + "isActive":1, + "createdAt":"2024-06-27T13:06:56.928007Z", + "updatedAt":"2024-06-27T13:06:56.931006Z", + "belongsToCurrentTenant":true + }, + { + "id":"92186655-166c-463c-9898-82e25f2f010a", + "name":"Metadata Services", + "code":"Metadata Services", + "isActive":1, + "createdAt":"2024-06-27T13:06:56.845006Z", + "updatedAt":"2024-06-27T13:06:56.854006Z", + "belongsToCurrentTenant":true + }, + { + "id":"a3ce0fb2-d72c-48bb-b322-7401940cb802", + "name":"Datasets", + "code":"datasets", + "isActive":1, + "createdAt":"2023-11-17T10:26:55.332111Z", + "updatedAt":"2024-05-01T10:34:07.029327Z", + "belongsToCurrentTenant":true + }, + { + "id":"7eeffb98-58fb-4921-82ec-e27f32f8e738", + "name":"Organisations", + "code":"organisations", + "isActive":1, + "createdAt":"2023-11-17T10:13:15.873808Z", + "updatedAt":"2024-02-16T15:35:47.874131Z", + "belongsToCurrentTenant":true + }, + { + "id":"3d372db5-a456-45e6-a845-e41e1a8311f8", + "name":"Projects", + "code":"projects", + "isActive":1, + "createdAt":"2023-11-17T08:55:05.190807Z", + "updatedAt":"2023-11-17T08:56:23.012619Z", + "belongsToCurrentTenant":true + }, + { + "id":"5a2112e7-ea99-4cfe-98a1-68665e26726e", + "name":"Researchers", + "code":"researchers", + "isActive":1, + "createdAt":"2023-11-16T18:21:43.272982Z", + "updatedAt":"2024-04-17T09:44:53.656849Z", + "belongsToCurrentTenant":true + }, + { + "id":"9ec2000d-95c7-452e-b356-755fc8e2574c", + "name":"Services", + "code":"services", + "isActive":1, + "createdAt":"2023-11-16T17:57:22.081053Z", + "updatedAt":"2024-02-16T09:07:13.944104Z", + "belongsToCurrentTenant":true + }, + { + "id":"ab7cdd93-bea2-440d-880d-3846dad80b21", + "name":"Taxonomies", + "code":"taxonomies", + "isActive":1, + "createdAt":"2023-11-16T17:48:09.769599Z", + "updatedAt":"2024-04-25T12:36:57.923984Z", + "belongsToCurrentTenant":true + }, + { + "id":"8ec7556b-749d-4c4a-a4b9-43d064693795", + "name":"Journals", + "code":"journals", + "isActive":1, + "createdAt":"2023-11-16T17:40:12.811667Z", + "updatedAt":"2024-02-16T09:09:22.816978Z", + "belongsToCurrentTenant":true + }, + { + "id":"1e927daa-b856-443f-96da-22f325f7322f", + "name":"Publication Repositories", + "code":"pubRepositories", + "isActive":1, + "createdAt":"2023-11-16T17:17:40.882679Z", + "updatedAt":"2024-05-01T11:52:50.297337Z", + "belongsToCurrentTenant":true + } + ], + "count":17 + } + """; + + } + } diff --git a/backend/web/src/main/resources/config/swagger.yml b/backend/web/src/main/resources/config/swagger.yml index 73ffb5983..2d97790b1 100644 --- a/backend/web/src/main/resources/config/swagger.yml +++ b/backend/web/src/main/resources/config/swagger.yml @@ -11,7 +11,7 @@ springdoc: displayName: Current packagesToScan: org.opencdmp.controllers packagesToExclude: org.opencdmp.controllers.publicapi - pathsToMatch: "/api/dmp/**, /api/description/**, /api/description-template/**, /api/description-template-type/**, /api/dmp-blueprint/**, /api/entity-doi/**, /api/deposit/**, /api/file-transformer/**, /api/tag/**" + pathsToMatch: "/api/plan/**, /api/description/**, /api/description-template/**, /api/description-template-type/**, /api/plan-blueprint/**, /api/entity-doi/**, /api/deposit/**, /api/file-transformer/**, /api/tag/**, /api/reference/**, /api/reference-type/**" swaggerUi: enabled: true useRootPath: true