From b0da9b6b89e852ca67c011eb9ac14ee84eec9c25 Mon Sep 17 00:00:00 2001 From: Thomas Georgios Giannos Date: Fri, 28 Jun 2024 15:31:42 +0300 Subject: [PATCH] Adding deposit and transformer swagger docs, adding missing response schemas --- .../controllers/DepositController.java | 62 +++++++++++++++--- .../controllers/DescriptionController.java | 43 ++++++++++--- .../DescriptionTemplateController.java | 41 ++++++++++-- .../DescriptionTemplateTypeController.java | 17 ++++- .../controllers/DmpBlueprintController.java | 42 +++++++++--- .../opencdmp/controllers/DmpController.java | 64 +++++++++++++++---- .../controllers/EntityDoiController.java | 18 ++++-- .../FileTransformerController.java | 28 +++++++- .../controllers/swagger/SwaggerHelpers.java | 38 +++++++++++ .../web/src/main/resources/config/swagger.yml | 2 +- 10 files changed, 300 insertions(+), 55 deletions(-) diff --git a/backend/web/src/main/java/org/opencdmp/controllers/DepositController.java b/backend/web/src/main/java/org/opencdmp/controllers/DepositController.java index 2e2d20859..136e13ac2 100644 --- a/backend/web/src/main/java/org/opencdmp/controllers/DepositController.java +++ b/backend/web/src/main/java/org/opencdmp/controllers/DepositController.java @@ -7,7 +7,18 @@ 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.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.tags.Tag; import org.opencdmp.audit.AuditableAction; +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.model.EntityDoi; import org.opencdmp.model.censorship.EntityDoiCensor; import org.opencdmp.model.censorship.deposit.DepositConfigurationCensor; @@ -35,11 +46,12 @@ import java.util.Map; @RestController @CrossOrigin @RequestMapping("/api/deposit/") +@Tag(name = "Deposit", description = "Manage deposit repositories, make deposits") +@SwaggerCommonErrorResponses public class DepositController { private static final LoggerService logger = new LoggerService(LoggerFactory.getLogger(DepositController.class)); - private final DepositService depositService; private final CensorFactory censorFactory; @@ -53,11 +65,18 @@ public class DepositController { this.depositService = depositService; this.censorFactory = censorFactory; this.auditService = auditService; - this.messageSource = messageSource; + this.messageSource = messageSource; } @GetMapping("/repositories/available") - public List getAvailableRepos(FieldSet fieldSet) throws InvalidApplicationException, InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException { + @OperationWithTenantHeader(summary = "Fetch all repositories", description = SwaggerHelpers.Deposit.endpoint_get_available_repos, + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + array = @ArraySchema( + schema = @Schema( + implementation = DepositConfiguration.class + ))) + )) + public List getAvailableRepos(FieldSet fieldSet) throws InvalidApplicationException, InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException { logger.debug(new MapLogEntry("retrieving" + DepositConfiguration.class.getSimpleName()).And("fields", fieldSet)); this.censorFactory.censor(DepositConfigurationCensor.class).censor(fieldSet, null); @@ -71,6 +90,13 @@ public class DepositController { } @PostMapping("/deposit") + @OperationWithTenantHeader(summary = "Make a plan deposit request", description = SwaggerHelpers.Deposit.endpoint_deposit, + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = EntityDoi.class + )) + )) + @Swagger400 @Transactional @ValidationFilterAnnotation(validator = DepositRequest.DepositRequestValidator.ValidatorName, argumentName = "model") public EntityDoi deposit(@RequestBody DepositRequest model) throws Exception { @@ -86,15 +112,26 @@ public class DepositController { } @GetMapping("/repositories/{repositoryId}") - public org.opencdmp.model.deposit.DepositConfiguration getRepository(@PathVariable("repositoryId") String repositoryId, FieldSet fieldSet) throws InvalidApplicationException, InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException { + @OperationWithTenantHeader(summary = "Fetch a specific deposit repository by id", description = SwaggerHelpers.Deposit.endpoint_get_repository, + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = DepositConfiguration.class + )) + )) + @Swagger404 + public DepositConfiguration getRepository( + @Parameter(name = "repositoryId", description = "The id of a repository to fetch", example = "zenodo", required = true) @PathVariable("repositoryId") String repositoryId, + @Parameter(name = "fieldSet", description = SwaggerHelpers.Commons.fieldset_description, required = true) FieldSet fieldSet + ) throws InvalidApplicationException, InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException { logger.debug(new MapLogEntry("retrieving" + DepositConfiguration.class.getSimpleName()).And("fields", fieldSet).And("repositoryId", repositoryId)); this.censorFactory.censor(DepositConfigurationCensor.class).censor(fieldSet, null); List models = this.depositService.getAvailableConfigurations(fieldSet); - org.opencdmp.model.deposit.DepositConfiguration model = models.stream().filter(x-> x.getRepositoryId().equals(repositoryId)).findFirst().orElse(null); - if (model == null) throw new MyNotFoundException(this.messageSource.getMessage("General_ItemNotFound", new Object[]{repositoryId, org.opencdmp.model.deposit.DepositConfiguration.class.getSimpleName()}, LocaleContextHolder.getLocale())); - + org.opencdmp.model.deposit.DepositConfiguration model = models.stream().filter(x -> x.getRepositoryId().equals(repositoryId)).findFirst().orElse(null); + if (model == null) + throw new MyNotFoundException(this.messageSource.getMessage("General_ItemNotFound", new Object[]{repositoryId, org.opencdmp.model.deposit.DepositConfiguration.class.getSimpleName()}, LocaleContextHolder.getLocale())); + this.auditService.track(AuditableAction.Deposit_GetRepository, Map.ofEntries( new AbstractMap.SimpleEntry("repositoryId", repositoryId), new AbstractMap.SimpleEntry("fields", fieldSet) @@ -104,7 +141,16 @@ public class DepositController { } @GetMapping("/repositories/{repositoryId}/logo") - public String getLogo(@PathVariable("repositoryId") String repositoryId) throws InvalidApplicationException, InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException { + @OperationWithTenantHeader(summary = "Fetch a specific deposit repository logo by id", description = SwaggerHelpers.Deposit.endpoint_get_logo, + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = String.class + )) + )) + @Swagger404 + public String getLogo( + @Parameter(name = "repositoryId", description = "The id of a repository of which to fetch the logo", example = "zenodo", required = true) @PathVariable("repositoryId") String repositoryId + ) throws InvalidApplicationException, InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException { logger.debug(new MapLogEntry("get logo" + DepositConfiguration.class.getSimpleName()).And("repositoryId", repositoryId)); String logo = this.depositService.getLogo(repositoryId); diff --git a/backend/web/src/main/java/org/opencdmp/controllers/DescriptionController.java b/backend/web/src/main/java/org/opencdmp/controllers/DescriptionController.java index 16ab7bbac..c6a25ae60 100644 --- a/backend/web/src/main/java/org/opencdmp/controllers/DescriptionController.java +++ b/backend/web/src/main/java/org/opencdmp/controllers/DescriptionController.java @@ -195,7 +195,12 @@ public class DescriptionController { } @GetMapping("{id}") - @OperationWithTenantHeader(summary = "Fetch a specific description by id") + @OperationWithTenantHeader(summary = "Fetch a specific description by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = Description.class + )) + )) @Swagger404 public Description get( @Parameter(name = "id", description = "The id of a description to fetch", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id, @@ -220,7 +225,12 @@ public class DescriptionController { } @PostMapping("persist") - @OperationWithTenantHeader(summary = "Create a new or update an existing description") + @OperationWithTenantHeader(summary = "Create a new or update an existing description", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = Description.class + )) + )) @Swagger400 @Swagger404 @Transactional @@ -243,7 +253,12 @@ public class DescriptionController { } @PostMapping("persist-status") - @OperationWithTenantHeader(summary = "Update the status of an existing description") + @OperationWithTenantHeader(summary = "Update the status of an existing description", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = Description.class + )) + )) @Swagger400 @Swagger404 @Transactional @@ -298,7 +313,8 @@ public class DescriptionController { } @DeleteMapping("{id}") - @OperationWithTenantHeader(summary = "Delete a description by id") + @OperationWithTenantHeader(summary = "Delete a description by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 @Transactional public void delete( @@ -312,7 +328,8 @@ public class DescriptionController { } @GetMapping("{id}/export/{type}") - @OperationWithTenantHeader(summary = "Export a description in various formats by id") + @OperationWithTenantHeader(summary = "Export a description in various formats by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 public ResponseEntity export( @Parameter(name = "id", description = "The id of a description to export", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id, @@ -324,7 +341,12 @@ public class DescriptionController { } @PostMapping("field-file/upload") - @OperationWithTenantHeader(summary = "Upload a file attachment on a field that supports it") + @OperationWithTenantHeader(summary = "Upload a file attachment on a field that supports it", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = StorageFile.class + )) + )) @Swagger400 @Swagger404 @Transactional @@ -348,7 +370,8 @@ public class DescriptionController { } @GetMapping("{id}/field-file/{fileId}") - @OperationWithTenantHeader(summary = "Fetch a field file attachment as byte array") + @OperationWithTenantHeader(summary = "Fetch a field file attachment as byte array", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 public ResponseEntity getFieldFile( @Parameter(name = "id", description = "The id of a description", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id, @@ -377,7 +400,8 @@ public class DescriptionController { } @PostMapping("update-description-template") - @OperationWithTenantHeader(summary = "Change the template of a description") + @OperationWithTenantHeader(summary = "Change the template of a description", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger400 @Swagger404 @Transactional @@ -394,7 +418,8 @@ public class DescriptionController { } @RequestMapping(method = RequestMethod.GET, value = "/xml/export/{id}", produces = "application/xml") - @OperationWithTenantHeader(summary = "Export a description in xml format by id") + @OperationWithTenantHeader(summary = "Export a description in xml format by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 public @ResponseBody ResponseEntity getXml( @Parameter(name = "id", description = "The id of a description to export", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable UUID id diff --git a/backend/web/src/main/java/org/opencdmp/controllers/DescriptionTemplateController.java b/backend/web/src/main/java/org/opencdmp/controllers/DescriptionTemplateController.java index 591988ef4..0dcc5e3c6 100644 --- a/backend/web/src/main/java/org/opencdmp/controllers/DescriptionTemplateController.java +++ b/backend/web/src/main/java/org/opencdmp/controllers/DescriptionTemplateController.java @@ -134,7 +134,12 @@ public class DescriptionTemplateController { } @GetMapping("{id}") - @OperationWithTenantHeader(summary = "Fetch a specific description template by id") + @OperationWithTenantHeader(summary = "Fetch a specific description template by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = DescriptionTemplate.class + )) + )) @Swagger404 public DescriptionTemplate get( @Parameter(name = "id", description = "The id of a description template to fetch", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id, @@ -159,7 +164,12 @@ public class DescriptionTemplateController { } @PostMapping("persist") - @OperationWithTenantHeader(summary = "Create a new or update an existing description template") + @OperationWithTenantHeader(summary = "Create a new or update an existing description template", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = DescriptionTemplate.class + )) + )) @Swagger400 @Swagger404 @Transactional @@ -182,7 +192,8 @@ public class DescriptionTemplateController { } @DeleteMapping("{id}") - @OperationWithTenantHeader(summary = "Delete a description template by id") + @OperationWithTenantHeader(summary = "Delete a description template by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 @Transactional public void delete( @@ -196,7 +207,12 @@ public class DescriptionTemplateController { } @GetMapping("clone/{id}") - @OperationWithTenantHeader(summary = "Clone a description template by id") + @OperationWithTenantHeader(summary = "Clone a description template by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = DescriptionTemplate.class + )) + )) @Swagger404 public DescriptionTemplate buildClone( @Parameter(name = "id", description = "The id of a description template to clone", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id, @@ -218,7 +234,12 @@ public class DescriptionTemplateController { } @PostMapping("new-version") - @OperationWithTenantHeader(summary = "Create a new version of a description template") + @OperationWithTenantHeader(summary = "Create a new version of a description template", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = DescriptionTemplate.class + )) + )) @Swagger400 @Swagger404 @Transactional @@ -240,7 +261,8 @@ public class DescriptionTemplateController { } @RequestMapping(method = RequestMethod.GET, value = "/xml/export/{id}", produces = "application/xml") - @OperationWithTenantHeader(summary = "Export a description template in xml by id") + @OperationWithTenantHeader(summary = "Export a description template in xml by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 public @ResponseBody ResponseEntity getXml( @Parameter(name = "id", description = "The id of a description template to export", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable UUID id @@ -257,7 +279,12 @@ public class DescriptionTemplateController { } @RequestMapping(method = RequestMethod.POST, value = {"/xml/import/{groupId}", "/xml/import"}) - @OperationWithTenantHeader(summary = "Import a description template from an xml file") + @OperationWithTenantHeader(summary = "Import a description template from an xml file", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = DescriptionTemplate.class + )) + )) @Transactional public DescriptionTemplate importXml( @RequestParam("file") MultipartFile file, diff --git a/backend/web/src/main/java/org/opencdmp/controllers/DescriptionTemplateTypeController.java b/backend/web/src/main/java/org/opencdmp/controllers/DescriptionTemplateTypeController.java index 49c404928..dabe332c1 100644 --- a/backend/web/src/main/java/org/opencdmp/controllers/DescriptionTemplateTypeController.java +++ b/backend/web/src/main/java/org/opencdmp/controllers/DescriptionTemplateTypeController.java @@ -116,7 +116,12 @@ public class DescriptionTemplateTypeController { } @GetMapping("{id}") - @OperationWithTenantHeader(summary = "Fetch a specific description template type by id") + @OperationWithTenantHeader(summary = "Fetch a specific description template type by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = DescriptionTemplateType.class + )) + )) @Swagger404 public DescriptionTemplateType Get( @Parameter(name = "id", description = "The id of a description template type to fetch", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id, @@ -141,7 +146,12 @@ public class DescriptionTemplateTypeController { } @PostMapping("persist") - @OperationWithTenantHeader(summary = "Create a new or update an existing description template type") + @OperationWithTenantHeader(summary = "Create a new or update an existing description template type", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = DescriptionTemplateType.class + )) + )) @Swagger400 @Swagger404 @Transactional @@ -162,7 +172,8 @@ public class DescriptionTemplateTypeController { } @DeleteMapping("{id}") - @OperationWithTenantHeader(summary = "Delete a description template type by id") + @OperationWithTenantHeader(summary = "Delete a description template type by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 @Transactional public void Delete( diff --git a/backend/web/src/main/java/org/opencdmp/controllers/DmpBlueprintController.java b/backend/web/src/main/java/org/opencdmp/controllers/DmpBlueprintController.java index c58fc4b0a..bc344b6e5 100644 --- a/backend/web/src/main/java/org/opencdmp/controllers/DmpBlueprintController.java +++ b/backend/web/src/main/java/org/opencdmp/controllers/DmpBlueprintController.java @@ -29,7 +29,6 @@ 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.DmpBlueprintEntity; -import org.opencdmp.model.DescriptionTemplateType; import org.opencdmp.model.builder.dmpblueprint.DmpBlueprintBuilder; import org.opencdmp.model.censorship.dmpblueprint.DmpBlueprintCensor; import org.opencdmp.model.dmpblueprint.DmpBlueprint; @@ -127,7 +126,12 @@ public class DmpBlueprintController { } @GetMapping("{id}") - @OperationWithTenantHeader(summary = "Fetch a specific plan blueprint by id") + @OperationWithTenantHeader(summary = "Fetch a specific plan blueprint by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = DmpBlueprint.class + )) + )) @Swagger404 public DmpBlueprint get( @Parameter(name = "id", description = "The id of a plan blueprint to fetch", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id, @@ -151,7 +155,12 @@ public class DmpBlueprintController { } @PostMapping("persist") - @OperationWithTenantHeader(summary = "Create a new or update an existing plan blueprint") + @OperationWithTenantHeader(summary = "Create a new or update an existing plan blueprint", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = DmpBlueprint.class + )) + )) @Swagger400 @Swagger404 @Transactional @@ -174,7 +183,8 @@ public class DmpBlueprintController { } @DeleteMapping("{id}") - @OperationWithTenantHeader(summary = "Delete a plan blueprint by id") + @OperationWithTenantHeader(summary = "Delete a plan blueprint by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 @Transactional public void delete( @@ -188,7 +198,12 @@ public class DmpBlueprintController { } @GetMapping("clone/{id}") - @OperationWithTenantHeader(summary = "Clone a plan blueprint by id") + @OperationWithTenantHeader(summary = "Clone a plan blueprint by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = DmpBlueprint.class + )) + )) @Swagger404 public DmpBlueprint buildClone( @Parameter(name = "id", description = "The id of a plan blueprint to clone", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id, @@ -209,7 +224,12 @@ public class DmpBlueprintController { } @PostMapping("new-version") - @OperationWithTenantHeader(summary = "Create a new version of an existing plan blueprint") + @OperationWithTenantHeader(summary = "Create a new version of an existing plan blueprint", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = DmpBlueprint.class + )) + )) @Swagger400 @Swagger404 @Transactional @@ -230,7 +250,8 @@ public class DmpBlueprintController { } @RequestMapping(method = RequestMethod.GET, value = "/xml/export/{id}", produces = "application/xml") - @OperationWithTenantHeader(summary = "Export a plan blueprint in xml format by id") + @OperationWithTenantHeader(summary = "Export a plan blueprint in xml format by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 public @ResponseBody ResponseEntity getXml( @Parameter(name = "id", description = "The id of a plan blueprint to export", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable UUID id @@ -246,7 +267,12 @@ public class DmpBlueprintController { } @RequestMapping(method = RequestMethod.POST, value = {"/xml/import/{groupId}", "/xml/import"}) - @OperationWithTenantHeader(summary = "Import a plan blueprint from an xml file") + @OperationWithTenantHeader(summary = "Import a plan blueprint from an xml file", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = DmpBlueprint.class + )) + )) @Transactional public DmpBlueprint importXml( @RequestParam("file") MultipartFile file, diff --git a/backend/web/src/main/java/org/opencdmp/controllers/DmpController.java b/backend/web/src/main/java/org/opencdmp/controllers/DmpController.java index ae1fef59a..51fde57a4 100644 --- a/backend/web/src/main/java/org/opencdmp/controllers/DmpController.java +++ b/backend/web/src/main/java/org/opencdmp/controllers/DmpController.java @@ -179,7 +179,12 @@ public class DmpController { } @GetMapping("{id}") - @OperationWithTenantHeader(summary = "Fetch a specific plan by id") + @OperationWithTenantHeader(summary = "Fetch a specific plan by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = Dmp.class + )) + )) @Swagger404 public Dmp Get( @Parameter(name = "id", description = "The id of a plan to fetch", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id, @@ -204,7 +209,12 @@ public class DmpController { } @PostMapping("persist") - @OperationWithTenantHeader(summary = "Create a new or update an existing plan") + @OperationWithTenantHeader(summary = "Create a new or update an existing plan", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = Dmp.class + )) + )) @Swagger400 @Swagger404 @Transactional @@ -226,7 +236,8 @@ public class DmpController { } @DeleteMapping("{id}") - @OperationWithTenantHeader(summary = "Delete a plan by id") + @OperationWithTenantHeader(summary = "Delete a plan by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 @Transactional public void Delete( @@ -240,7 +251,8 @@ public class DmpController { } @PostMapping("finalize/{id}") - @OperationWithTenantHeader(summary = "Finalize a plan by id") + @OperationWithTenantHeader(summary = "Finalize a plan by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 @Transactional public boolean finalize( @@ -260,7 +272,8 @@ public class DmpController { } @GetMapping("undo-finalize/{id}") - @OperationWithTenantHeader(summary = "Undo the finalization of a plan by id (only possible if it is not already deposited)") + @OperationWithTenantHeader(summary = "Undo the finalization of a plan by id (only possible if it is not already deposited)", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 @Transactional public boolean undoFinalize( @@ -298,7 +311,12 @@ public class DmpController { } @PostMapping("clone") - @OperationWithTenantHeader(summary = "Create a clone of an existing plan") + @OperationWithTenantHeader(summary = "Create a clone of an existing plan", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = Dmp.class + )) + )) @Swagger400 @Swagger404 @Transactional @@ -322,7 +340,12 @@ public class DmpController { } @PostMapping("new-version") - @OperationWithTenantHeader(summary = "Create a new version of an existing plan") + @OperationWithTenantHeader(summary = "Create a new version of an existing plan", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = Dmp.class + )) + )) @Swagger400 @Swagger404 @Transactional @@ -380,7 +403,8 @@ public class DmpController { } @GetMapping("{id}/export/{transformerId}/{type}") - @OperationWithTenantHeader(summary = "Export a plan in various formats by id") + @OperationWithTenantHeader(summary = "Export a plan in various formats by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 public ResponseEntity export( @Parameter(name = "id", description = "The id of a plan to export", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id, @@ -432,7 +456,8 @@ public class DmpController { } @RequestMapping(method = RequestMethod.GET, value = "/xml/export/{id}", produces = "application/xml") - @OperationWithTenantHeader(summary = "Export a plan in xml format by id") + @OperationWithTenantHeader(summary = "Export a plan in xml format by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 public @ResponseBody ResponseEntity getXml( @Parameter(name = "id", description = "The id of a plan to export", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable UUID id @@ -448,7 +473,12 @@ public class DmpController { } @RequestMapping(method = RequestMethod.POST, value = "/xml/import") - @OperationWithTenantHeader(summary = "Import a plan from an xml file") + @OperationWithTenantHeader(summary = "Import a plan from an xml file", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = Dmp.class + )) + )) @Transactional public Dmp importXml( @RequestParam("file") MultipartFile file, @@ -467,7 +497,12 @@ public class DmpController { } @PostMapping("json/preprocessing") - @OperationWithTenantHeader(summary = "preprocessing a plan from an json file") + @OperationWithTenantHeader(summary = "Preprocess a plan from a json file", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = PreprocessingDmpModel.class + )) + )) @Transactional public PreprocessingDmpModel preprocessing( @RequestParam("fileId") UUID fileId, @@ -486,7 +521,12 @@ public class DmpController { } @PostMapping("json/import") - @OperationWithTenantHeader(summary = "Import a plan from an json file") + @OperationWithTenantHeader(summary = "Import a plan from an json file", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = Dmp.class + )) + )) @ValidationFilterAnnotation(validator = DmpCommonModelConfig.DmpCommonModelConfigValidator.ValidatorName, argumentName = "model") @Transactional public Dmp importJson( diff --git a/backend/web/src/main/java/org/opencdmp/controllers/EntityDoiController.java b/backend/web/src/main/java/org/opencdmp/controllers/EntityDoiController.java index 58ba122aa..742e091d5 100644 --- a/backend/web/src/main/java/org/opencdmp/controllers/EntityDoiController.java +++ b/backend/web/src/main/java/org/opencdmp/controllers/EntityDoiController.java @@ -30,7 +30,6 @@ import org.opencdmp.model.DescriptionTemplateType; import org.opencdmp.model.EntityDoi; import org.opencdmp.model.builder.EntityDoiBuilder; import org.opencdmp.model.censorship.EntityDoiCensor; -import org.opencdmp.model.dmpblueprint.DmpBlueprint; import org.opencdmp.model.persist.EntityDoiPersist; import org.opencdmp.model.result.QueryResult; import org.opencdmp.query.EntityDoiQuery; @@ -116,7 +115,12 @@ public class EntityDoiController { } @GetMapping("{id}") - @OperationWithTenantHeader(summary = "Fetch a specific entity doi by id") + @OperationWithTenantHeader(summary = "Fetch a specific entity doi by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = EntityDoi.class + )) + )) @Swagger404 public EntityDoi get( @Parameter(name = "id", description = "The id of an entity doi to fetch", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id, @@ -141,7 +145,12 @@ public class EntityDoiController { } @PostMapping("persist") - @OperationWithTenantHeader(summary = "Create a new or update an existing entity doi") + @OperationWithTenantHeader(summary = "Create a new or update an existing entity doi", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + schema = @Schema( + implementation = EntityDoi.class + )) + )) @Swagger400 @Swagger404 @Transactional @@ -162,7 +171,8 @@ public class EntityDoiController { } @DeleteMapping("{id}") - @OperationWithTenantHeader(summary = "Delete an entity doi by id") + @OperationWithTenantHeader(summary = "Delete an entity doi by id", description = "", + responses = @ApiResponse(description = "OK", responseCode = "200")) @Swagger404 @Transactional public void delete( diff --git a/backend/web/src/main/java/org/opencdmp/controllers/FileTransformerController.java b/backend/web/src/main/java/org/opencdmp/controllers/FileTransformerController.java index 0846f2ea7..14fd21e11 100644 --- a/backend/web/src/main/java/org/opencdmp/controllers/FileTransformerController.java +++ b/backend/web/src/main/java/org/opencdmp/controllers/FileTransformerController.java @@ -1,6 +1,15 @@ package org.opencdmp.controllers; +import io.swagger.v3.oas.annotations.media.ArraySchema; +import io.swagger.v3.oas.annotations.media.Content; +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 org.opencdmp.audit.AuditableAction; +import org.opencdmp.controllers.swagger.SwaggerHelpers; +import org.opencdmp.controllers.swagger.annotation.OperationWithTenantHeader; +import org.opencdmp.controllers.swagger.annotation.SwaggerCommonErrorResponses; +import org.opencdmp.model.deposit.DepositConfiguration; import org.opencdmp.model.file.ExportRequestModel; import org.opencdmp.model.file.FileEnvelope; import org.opencdmp.model.file.RepositoryFileFormat; @@ -29,6 +38,8 @@ import java.util.List; @RestController @CrossOrigin @RequestMapping(value = {"/api/file-transformer/"}) +@Tag(name = "File Transformers", description = "Manage file transformers, perform exports") +@SwaggerCommonErrorResponses public class FileTransformerController { private static final LoggerService logger = new LoggerService(LoggerFactory.getLogger(FileTransformerController.class)); @@ -43,6 +54,13 @@ public class FileTransformerController { } @GetMapping("/available") + @OperationWithTenantHeader(summary = "Fetch all transformers", description = SwaggerHelpers.FileTransformer.endpoint_get_available_transformers, + responses = @ApiResponse(description = "OK", responseCode = "200", content = @Content( + array = @ArraySchema( + schema = @Schema( + implementation = RepositoryFileFormat.class + ))) + )) public List getAvailableConfigurations() throws InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, InvalidApplicationException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException { logger.debug(new MapLogEntry("getAvailableConfigurations")); @@ -54,8 +72,10 @@ public class FileTransformerController { } @PostMapping("/export-dmp") - public ResponseEntity export(@RequestBody ExportRequestModel requestModel) throws InvalidApplicationException, IOException, InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException { - logger.debug(new MapLogEntry("exporting dmp")); + @OperationWithTenantHeader(summary = "Export a plan", description = SwaggerHelpers.FileTransformer.endpoint_export_plans, + responses = @ApiResponse(description = "OK", responseCode = "200")) + public ResponseEntity exportPlan(@RequestBody ExportRequestModel requestModel) throws InvalidApplicationException, IOException, InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException { + logger.debug(new MapLogEntry("exporting plan")); HttpHeaders headers = new HttpHeaders(); FileEnvelope fileEnvelope = this.fileTransformerService.exportDmp(requestModel.getId(), requestModel.getRepositoryId(), requestModel.getFormat()); @@ -66,8 +86,10 @@ public class FileTransformerController { } @PostMapping("/export-description") + @OperationWithTenantHeader(summary = "Export a description", description = SwaggerHelpers.FileTransformer.endpoint_export_descriptions, + responses = @ApiResponse(description = "OK", responseCode = "200")) public ResponseEntity exportDescription(@RequestBody ExportRequestModel requestModel) throws InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, InvalidApplicationException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException { - logger.debug(new MapLogEntry("exporting dmp")); + logger.debug(new MapLogEntry("exporting description")); HttpHeaders headers = new HttpHeaders(); FileEnvelope fileEnvelope = this.fileTransformerService.exportDescription(requestModel.getId(), requestModel.getRepositoryId(), requestModel.getFormat()); 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 c7114e0fa..ee20f7032 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 @@ -2550,6 +2550,23 @@ public class SwaggerHelpers { public static class FileTransformer { + public static final String endpoint_get_available_transformers = + """ + This endpoint is used to fetch all the available file transformers.
+ """; + + public static final String endpoint_export_plans = + """ + This endpoint is used to export a plan using a specific file transformer.
+ Choosing the transformer will determine the format of the export. + """; + + public static final String endpoint_export_descriptions = + """ + This endpoint is used to export a plan using a specific file transformer. + Choosing the transformer will determine the format of the export. + """; + } public static class EntityDoi { @@ -2815,10 +2832,31 @@ public class SwaggerHelpers { "count":118 } """; + } public static class Deposit { + public static final String endpoint_get_available_repos = + """ + This endpoint is used to fetch all the available deposit repositories. + """; + + public static final String endpoint_deposit = + """ + This endpoint is used to deposit a plan in a repository. + """; + + public static final String endpoint_get_repository = + """ + This endpoint is used to get information about a specific repository. + """; + + public static final String endpoint_get_logo = + """ + This endpoint is used to fetch the logo url of a repository. + """; + } } diff --git a/backend/web/src/main/resources/config/swagger.yml b/backend/web/src/main/resources/config/swagger.yml index 0310255b0..72d70a5b0 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/**" + pathsToMatch: "/api/dmp/**, /api/description/**, /api/description-template/**, /api/description-template-type/**, /api/dmp-blueprint/**, /api/entity-doi/**, /api/deposit/**, /api/file-transformer/**" swaggerUi: enabled: true useRootPath: true