MaDgiK-CITE
/
argos
13
0
Fork 0
Code Issues Pull Requests Projects Releases 3 Wiki Activity

Added swagger docs for references and their types

This commit is contained in:
Thomas Georgios Giannos 2024-07-04 17:28:21 +03:00
parent 85b80f6c29
commit 4c53014025
4 changed files with 646 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
backend/web/src/main/java/org/opencdmp/controllers/ReferenceController.java
View File

@ -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<Reference> 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<Reference> 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);

79
backend/web/src/main/java/org/opencdmp/controllers/ReferenceTypeController.java
View File

@ -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<ReferenceType> 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);

493
backend/web/src/main/java/org/opencdmp/controllers/swagger/SwaggerHelpers.java
View File

@ -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.<br/>
It also allows to restrict the results using a query object passed in the request body.<br/>
""";
public static final String endpoint_query_request_body =
"""
Let's explore the options this object gives us.
### <u>General query parameters:</u>
<ul>
<li><b>page:</b>
This is an object controlling the pagination of the results. It contains two properties.
</li>
<ul>
<li><b>offset:</b>
How many records to omit.
</li>
<li><b>size:</b>
How many records to include in each page.
</li>
</ul>
</ul>
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
}
```
<ul>
<li><b>order:</b>
This is an object controlling the ordering of the results.
It contains a list of strings called <i>items</i> with the names of the properties to use.
<br/>If the name of the property is prefixed with a <b>'-'</b>, the ordering direction is <b>DESC</b>. Otherwise, it is <b>ASC</b>.
</li>
</ul>
For example, if we wanted to order based on the field 'createdAt' in descending order, we would pass the following object:
```JSON
{
"items": [
"-createdAt"
],
}
```
<ul>
<li><b>metadata:</b>
This is an object containing metadata for the request. There is only one available option.
<ul>
<li><b>countAll:</b>
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.
<br/>The first option is useful for the UI clients to calculate how many result pages are available.
</li>
</ul>
</li>
<li><b>project:</b>
This is an object controlling the data projection of the results.
It contains a list of strings called <i>fields</i> with the names of the properties to project.
<br/>You can also include properties that are deeper in the object tree by prefixing them with dots.
</li>
</ul>
### <u>Reference specific query parameters:</u>
<ul>
<li><b>like:</b>
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.
</li>
<li><b>ids:</b>
This is a list and contains the ids we want to include in the response. <br/>If empty, every record is included.
</li>
<li><b>excludedIds:</b>
This is a list and contains the ids we want to exclude from the response. <br/>If empty, no record gets excluded.
</li>
<li><b>typeIds:</b>
This is a list and contains the ids of the types of the references we want to include in the response. <br/>If empty, every record is included.
</li>
<li><b>isActive:</b>
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].
<br/>If not present or if we pass [0,1], every record is included.
</li>
<li><b>sourceTypes:</b>
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 <i>Internal</i> or <i>External</i>. We add 0 or 1 to the list respectively.
<br/>If not present, every record is included.
</li>
</ul>
""";
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.<br/>
It also allows to restrict the results using a query object passed in the request body.<br/>
""";
public static final String endpoint_query_request_body =
"""
Let's explore the options this object gives us.
### <u>General query parameters:</u>
<ul>
<li><b>page:</b>
This is an object controlling the pagination of the results. It contains two properties.
</li>
<ul>
<li><b>offset:</b>
How many records to omit.
</li>
<li><b>size:</b>
How many records to include in each page.
</li>
</ul>
</ul>
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
}
```
<ul>
<li><b>order:</b>
This is an object controlling the ordering of the results.
It contains a list of strings called <i>items</i> with the names of the properties to use.
<br/>If the name of the property is prefixed with a <b>'-'</b>, the ordering direction is <b>DESC</b>. Otherwise, it is <b>ASC</b>.
</li>
</ul>
For example, if we wanted to order based on the field 'createdAt' in descending order, we would pass the following object:
```JSON
{
"items": [
"-createdAt"
],
}
```
<ul>
<li><b>metadata:</b>
This is an object containing metadata for the request. There is only one available option.
<ul>
<li><b>countAll:</b>
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.
<br/>The first option is useful for the UI clients to calculate how many result pages are available.
</li>
</ul>
</li>
<li><b>project:</b>
This is an object controlling the data projection of the results.
It contains a list of strings called <i>fields</i> with the names of the properties to project.
<br/>You can also include properties that are deeper in the object tree by prefixing them with dots.
</li>
</ul>
### <u>Reference type specific query parameters:</u>
<ul>
<li><b>like:</b>
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.
</li>
<li><b>ids:</b>
This is a list and contains the ids we want to include in the response. <br/>If empty, every record is included.
</li>
<li><b>excludedIds:</b>
This is a list and contains the ids we want to exclude from the response. <br/>If empty, no record gets excluded.
</li>
<li><b>isActive:</b>
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].
<br/>If not present or if we pass [0,1], every record is included.
</li>
<li><b>codes:</b>
This is a list and determines which records we want to include in the response, based on their code.
<br/>If not present, every record is included.
</li>
</ul>
""";
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
}
""";
}
}

2
backend/web/src/main/resources/config/swagger.yml
View File

@ -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