Added endpoint summaries for Swagger ui

backend/web/src/main/java/org/opencdmp/controllers/DescriptionController.java

@@ -11,6 +11,8 @@ 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.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.xml.bind.JAXBException;
 import org.opencdmp.audit.AuditableAction;
 import org.opencdmp.authorization.AuthorizationFlags;
@@ -64,6 +66,7 @@ import static org.opencdmp.authorization.AuthorizationFlags.Public;
 
 @RestController
 @RequestMapping(path = "api/description")
+@Tag(name = "Descriptions", description = "Manage descriptions")
 public class DescriptionController {
 
     private static final LoggerService logger = new LoggerService(LoggerFactory.getLogger(DescriptionController.class));
@@ -104,6 +107,7 @@ public class DescriptionController {
     }
 
     @PostMapping("public/query")
+    @Operation(summary = "Query public descriptions")
     public QueryResult<PublicDescription> publicQuery(@RequestBody DescriptionLookup lookup) throws MyApplicationException, MyForbiddenException {
         logger.debug("querying {}", PublicDescription.class.getSimpleName());
 
@@ -118,6 +122,7 @@ public class DescriptionController {
     }
 
     @GetMapping("public/{id}")
+    @Operation(summary = "Fetch a specific public description by id")
     public PublicDescription publicGet(@PathVariable("id") UUID id, FieldSet fieldSet) throws MyApplicationException, MyForbiddenException, MyNotFoundException {
         logger.debug(new MapLogEntry("retrieving" + PublicDescription.class.getSimpleName()).And("id", id).And("fields", fieldSet));
         fieldSet = this.fieldSetExpanderService.expand(fieldSet);
@@ -138,6 +143,7 @@ public class DescriptionController {
     }
 
     @PostMapping("query")
+    @Operation(summary = "Query all descriptions")
     public QueryResult<Description> query(@RequestBody DescriptionLookup lookup) throws MyApplicationException, MyForbiddenException {
         logger.debug("querying {}", Description.class.getSimpleName());
 
@@ -152,6 +158,7 @@ public class DescriptionController {
 
 
     @GetMapping("{id}")
+    @Operation(summary = "Fetch a specific description by id")
     public Description get(@PathVariable("id") UUID id, FieldSet fieldSet) throws MyApplicationException, MyForbiddenException, MyNotFoundException {
         logger.debug(new MapLogEntry("retrieving" + Description.class.getSimpleName()).And("id", id).And("fields", fieldSet));
         fieldSet = this.fieldSetExpanderService.expand(fieldSet);
@@ -172,6 +179,7 @@ public class DescriptionController {
     }
 
     @PostMapping("persist")
+    @Operation(summary = "Create a new or update an existing description")
     @Transactional
     @ValidationFilterAnnotation(validator = DescriptionPersist.DescriptionPersistValidator.ValidatorName, argumentName = "model")
     public Description persist(@RequestBody DescriptionPersist model, FieldSet fieldSet) throws MyApplicationException, MyForbiddenException, MyNotFoundException, InvalidApplicationException, IOException {
@@ -189,6 +197,7 @@ public class DescriptionController {
     }
 
     @PostMapping("persist-status")
+    @Operation(summary = "Update the status of an existing description")
     @Transactional
     @ValidationFilterAnnotation(validator = DescriptionStatusPersist.DescriptionStatusPersistValidator.ValidatorName, argumentName = "model")
     public Description persistStatus(@RequestBody DescriptionStatusPersist model, FieldSet fieldSet) throws MyApplicationException, MyForbiddenException, MyNotFoundException, IOException, InvalidApplicationException {
@@ -206,6 +215,7 @@ public class DescriptionController {
     }
 
     @PostMapping("get-description-section-permissions")
+    @Operation(summary = "Fetch the section specific user permissions")
     @ValidationFilterAnnotation(validator = DescriptionSectionPermissionResolver.DescriptionSectionPermissionResolverPersistValidator.ValidatorName, argumentName = "model")
     public Map<UUID, List<String>> getDescriptionSectionPermissions(@RequestBody DescriptionSectionPermissionResolver model) {
         logger.debug(new MapLogEntry("persisting" + Description.class.getSimpleName()).And("model", model));
@@ -219,6 +229,7 @@ public class DescriptionController {
     }
 
     @GetMapping("validate")
+    @Operation(summary = "Validate if a description is ready for finalization by id")
     public List<DescriptionValidationResult> validate(@RequestParam("descriptionIds") List<UUID> descriptionIds) throws MyApplicationException, MyForbiddenException, MyNotFoundException, InvalidApplicationException {
         logger.debug(new MapLogEntry("validating" + Description.class.getSimpleName()).And("descriptionIds", descriptionIds));
 
@@ -234,6 +245,7 @@ public class DescriptionController {
     }
 
     @DeleteMapping("{id}")
+    @Operation(summary = "Delete a description by id")
     @Transactional
     public void delete(@PathVariable("id") UUID id) throws MyForbiddenException, InvalidApplicationException, IOException {
         logger.debug(new MapLogEntry("retrieving" + Description.class.getSimpleName()).And("id", id));
@@ -244,6 +256,7 @@ public class DescriptionController {
     }
 
     @GetMapping("{id}/export/{type}")
+    @Operation(summary = "Export a description in various formats by id")
     public ResponseEntity<byte[]> export(@PathVariable("id") UUID id, @PathVariable("type") String exportType) throws InvalidApplicationException, IOException, InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException {
         logger.debug(new MapLogEntry("exporting description"));
 
@@ -251,6 +264,7 @@ public class DescriptionController {
     }
 
     @PostMapping("field-file/upload")
+    @Operation(summary = "Upload a file attachment on a field that supports it")
     @Transactional
     @ValidationFilterAnnotation(validator = DescriptionFieldFilePersist.PersistValidator.ValidatorName, argumentName = "model")
     public StorageFile uploadFieldFiles(@RequestParam("file") MultipartFile file, @RequestParam("model") DescriptionFieldFilePersist model, FieldSet fieldSet) throws IOException {
@@ -268,6 +282,7 @@ public class DescriptionController {
     }
 
     @GetMapping("{id}/field-file/{fileId}")
+    @Operation(summary = "Fetch a field file attachment as byte array")
     public ResponseEntity<ByteArrayResource> getFieldFile(@PathVariable("id") UUID id, @PathVariable("fileId") UUID fileId) throws MyApplicationException, MyForbiddenException, MyNotFoundException {
         logger.debug(new MapLogEntry("get Field File" + Description.class.getSimpleName()).And("id", id).And("fileId", fileId));
 
@@ -290,6 +305,7 @@ public class DescriptionController {
     }
 
     @PostMapping("update-description-template")
+    @Operation(summary = "Change the template of a description")
     @Transactional
     @ValidationFilterAnnotation(validator = UpdateDescriptionTemplatePersist.UpdateDescriptionTemplatePersistValidator.ValidatorName, argumentName = "model")
     public Boolean updateDescriptionTemplate(@RequestBody UpdateDescriptionTemplatePersist model) throws MyApplicationException, MyForbiddenException, MyNotFoundException, InvalidApplicationException, IOException, JAXBException {
@@ -304,6 +320,7 @@ public class DescriptionController {
     }
 
     @RequestMapping(method = RequestMethod.GET, value = "/xml/export/{id}", produces = "application/xml")
+    @Operation(summary = "Export a description in xml format by id")
     public @ResponseBody ResponseEntity<byte[]> getXml(@PathVariable UUID id) throws JAXBException, ParserConfigurationException, IOException, InstantiationException, IllegalAccessException, SAXException, InvalidApplicationException {
         logger.debug(new MapLogEntry("export" + DmpBlueprint.class.getSimpleName()).And("id", id));
 

backend/web/src/main/java/org/opencdmp/controllers/DmpController.java

@@ -11,6 +11,8 @@ 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.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.xml.bind.JAXBException;
 import org.opencdmp.audit.AuditableAction;
 import org.opencdmp.authorization.AuthorizationFlags;
@@ -57,6 +59,7 @@ import static org.opencdmp.authorization.AuthorizationFlags.Public;
 
 @RestController
 @RequestMapping(path = "api/dmp")
+@Tag(name = "Plans", description = "Manage plans")
 public class DmpController {
 
     private static final LoggerService logger = new LoggerService(LoggerFactory.getLogger(DmpController.class));
@@ -93,6 +96,7 @@ public class DmpController {
     }    
     
     @PostMapping("public/query")
+    @Operation(summary = "Query public published plans")
     public QueryResult<PublicDmp> publicQuery(@RequestBody DmpLookup lookup) throws MyApplicationException, MyForbiddenException {
         logger.debug("querying {}", Dmp.class.getSimpleName());
 
@@ -107,6 +111,7 @@ public class DmpController {
     }
 
     @GetMapping("public/{id}")
+    @Operation(summary = "Fetch a specific public published plan by id")
     public PublicDmp publicGet(@PathVariable("id") UUID id, FieldSet fieldSet, Locale locale) throws MyApplicationException, MyForbiddenException, MyNotFoundException {
         logger.debug(new MapLogEntry("retrieving" + Dmp.class.getSimpleName()).And("id", id).And("fields", fieldSet));
 
@@ -126,6 +131,7 @@ public class DmpController {
     }
 
     @PostMapping("query")
+    @Operation(summary = "Query all plans")
     public QueryResult<Dmp> Query(@RequestBody DmpLookup lookup) throws MyApplicationException, MyForbiddenException {
         logger.debug("querying {}", Dmp.class.getSimpleName());
 
@@ -139,6 +145,7 @@ public class DmpController {
     }
 
     @GetMapping("{id}")
+    @Operation(summary = "Fetch a specific plan by id")
     public Dmp Get(@PathVariable("id") UUID id, FieldSet fieldSet, Locale locale) throws MyApplicationException, MyForbiddenException, MyNotFoundException {
         logger.debug(new MapLogEntry("retrieving" + Dmp.class.getSimpleName()).And("id", id).And("fields", fieldSet));
 
@@ -158,6 +165,7 @@ public class DmpController {
     }
 
     @PostMapping("persist")
+    @Operation(summary = "Create a new or update an existing plan")
     @Transactional
     @ValidationFilterAnnotation(validator = DmpPersist.DmpPersistValidator.ValidatorName, argumentName = "model")
     public Dmp Persist(@RequestBody DmpPersist model, FieldSet fieldSet) throws MyApplicationException, MyForbiddenException, MyNotFoundException, InvalidApplicationException, IOException, JAXBException {
@@ -174,6 +182,7 @@ public class DmpController {
     }
 
     @DeleteMapping("{id}")
+    @Operation(summary = "Delete a plan by id")
     @Transactional
     public void Delete(@PathVariable("id") UUID id) throws MyForbiddenException, InvalidApplicationException, IOException {
         logger.debug(new MapLogEntry("retrieving" + Dmp.class.getSimpleName()).And("id", id));
@@ -184,6 +193,7 @@ public class DmpController {
     }
 
     @PostMapping("finalize/{id}")
+    @Operation(summary = "Finalize a plan by id")
     @Transactional
     public boolean finalize(@PathVariable("id") UUID id, @RequestBody DescriptionsToBeFinalized descriptions) throws MyApplicationException, MyForbiddenException, MyNotFoundException, InvalidApplicationException, IOException {
         logger.debug(new MapLogEntry("finalizing" + Dmp.class.getSimpleName()).And("id", id).And("descriptionIds", descriptions.getDescriptionIds()));
@@ -199,6 +209,7 @@ public class DmpController {
     }
 
     @GetMapping("undo-finalize/{id}")
+    @Operation(summary = "Undo the finalization of a plan by id (only possible if it is not already deposited)")
     @Transactional
     public boolean undoFinalize(@PathVariable("id") UUID id, FieldSet fieldSet) throws MyApplicationException, MyForbiddenException, MyNotFoundException, InvalidApplicationException, IOException, JAXBException {
         logger.debug(new MapLogEntry("undo-finalizing" + Dmp.class.getSimpleName()).And("id", id));
@@ -215,6 +226,7 @@ public class DmpController {
     }
 
     @GetMapping("validate/{id}")
+    @Operation(summary = "Validate if a plan is ready for finalization by id")
     public DmpValidationResult validate(@PathVariable("id") UUID id) throws MyApplicationException, MyForbiddenException, MyNotFoundException, InvalidApplicationException {
         logger.debug(new MapLogEntry("validating" + Dmp.class.getSimpleName()).And("id", id));
 
@@ -230,6 +242,7 @@ public class DmpController {
     }
 
     @PostMapping("clone")
+    @Operation(summary = "Create a clone of an existing plan")
     @Transactional
     @ValidationFilterAnnotation(validator = CloneDmpPersist.CloneDmpPersistValidator.ValidatorName, argumentName = "model")
     public Dmp buildClone(@RequestBody CloneDmpPersist model, FieldSet fieldSet) throws MyApplicationException, MyForbiddenException, MyNotFoundException, IOException, InvalidApplicationException {
@@ -248,6 +261,7 @@ public class DmpController {
     }
 
     @PostMapping("new-version")
+    @Operation(summary = "Create a new version of an existing plan")
     @Transactional
     @ValidationFilterAnnotation(validator = NewVersionDmpPersist.NewVersionDmpPersistValidator.ValidatorName, argumentName = "model")
     public Dmp createNewVersion(@RequestBody NewVersionDmpPersist model, FieldSet fieldSet) throws MyApplicationException, MyForbiddenException, MyNotFoundException, JAXBException, IOException, TransformerException, InvalidApplicationException, ParserConfigurationException {
@@ -264,6 +278,7 @@ public class DmpController {
     }
 
     @PostMapping("{id}/assign-users")
+    @Operation(summary = "Assign users to the plan by id")
     @Transactional
     @ValidationFilterAnnotation(validator = DmpUserPersist.DmpUserPersistValidator.ValidatorName, argumentName = "model")
     public QueryResult<DmpUser> assignUsers(@PathVariable("id") UUID id, @RequestBody List<DmpUserPersist> model, FieldSet fieldSet) throws InvalidApplicationException, IOException {
@@ -280,6 +295,7 @@ public class DmpController {
     }
 
     @PostMapping("remove-user")
+    @Operation(summary = "Remove a user association with the plan")
     @Transactional
     @ValidationFilterAnnotation(validator = DmpUserRemovePersist.DmpUserRemovePersistValidator.ValidatorName, argumentName = "model")
     public QueryResult<Dmp> removeUser(@RequestBody DmpUserRemovePersist model, FieldSet fieldSet) throws InvalidApplicationException, IOException {
@@ -296,6 +312,7 @@ public class DmpController {
     }
 
     @GetMapping("{id}/export/{transformerId}/{type}")
+    @Operation(summary = "Export a plan in various formats by id")
     public ResponseEntity<byte[]> export(@PathVariable("id") UUID id, @PathVariable("transformerId") String transformerId, @PathVariable("type") String exportType) throws InvalidApplicationException, IOException, InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException {
         logger.debug(new MapLogEntry("exporting dmp").And("id", id).And("transformerId", transformerId).And("exportType", exportType));
 
@@ -309,6 +326,7 @@ public class DmpController {
     }
 
     @PostMapping("{id}/invite-users")
+    @Operation(summary = "Send user invitations for the plan by id")
     @Transactional
     @ValidationFilterAnnotation(validator = DmpUserInvitePersist.DmpUserInvitePersistValidator.ValidatorName, argumentName = "model")
     public boolean inviteUsers(@PathVariable("id") UUID id, @RequestBody DmpUserInvitePersist model) throws InvalidApplicationException, JAXBException, IOException {
@@ -324,6 +342,7 @@ public class DmpController {
     }
 
     @GetMapping("{id}/token/{token}/invite-accept")
+    @Operation(summary = "Accept an invitation token for a plan by id")
     @Transactional
     public boolean acceptInvitation(@PathVariable("id") UUID id, @PathVariable("token") String token) throws InvalidApplicationException, JAXBException, IOException {
         logger.debug(new MapLogEntry("inviting users to dmp").And("id", id));
@@ -338,6 +357,7 @@ public class DmpController {
     }
 
     @RequestMapping(method = RequestMethod.GET, value = "/xml/export/{id}", produces = "application/xml")
+    @Operation(summary = "Export a plan in xml format by id")
     public @ResponseBody ResponseEntity<byte[]> getXml(@PathVariable UUID id) throws JAXBException, ParserConfigurationException, IOException, InstantiationException, IllegalAccessException, SAXException, InvalidApplicationException {
         logger.debug(new MapLogEntry("export" + Dmp.class.getSimpleName()).And("id", id));
 
@@ -350,6 +370,7 @@ public class DmpController {
     }
 
     @RequestMapping(method = RequestMethod.POST, value = "/xml/import")
+    @Operation(summary = "Import a plan from an xml file")
     @Transactional
     public Dmp importXml(@RequestParam("file") MultipartFile file, @RequestParam("label") String label, FieldSet fields) throws JAXBException, ParserConfigurationException, IOException, InstantiationException, IllegalAccessException, SAXException, InvalidApplicationException, TransformerException {
         logger.debug(new MapLogEntry("import xml" + Dmp.class.getSimpleName()).And("file", file).And("label", label));
@@ -364,6 +385,7 @@ public class DmpController {
     }
 
     @PostMapping("json/import")
+    @Operation(summary = "Import a plan from an json file")
     @Transactional
     public Dmp importJson(@RequestParam("file") MultipartFile file, @RequestParam("label") String label, @RequestParam("repositoryId") String repositoryId, @RequestParam("format") String format, FieldSet fields) throws InvalidAlgorithmParameterException, JAXBException, NoSuchPaddingException, IllegalBlockSizeException, InvalidApplicationException, IOException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException {
         logger.debug(new MapLogEntry("import json" + Dmp.class.getSimpleName()).And("transformerId", repositoryId).And("file", file).And("label", label));