Adding parameter information on description endpoints.

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

@@ -184,8 +184,8 @@ public class DescriptionController {
     @Operation(summary = "Fetch a specific description by id")
     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,
-            @Parameter(name = "fieldSet", description = "This is an object containing a list of the properties you wish to include in the response, similar to the 'project' attribute on queries.", required = true) FieldSet fieldSet)
+            @Parameter(name = "fieldSet", description = SwaggerHelpers.fieldset_description, required = true) FieldSet fieldSet
-            throws MyApplicationException, MyForbiddenException, MyNotFoundException {
+    ) throws MyApplicationException, MyForbiddenException, MyNotFoundException {
         logger.debug(new MapLogEntry("retrieving" + Description.class.getSimpleName()).And("id", id).And("fields", fieldSet));
         fieldSet = this.fieldSetExpanderService.expand(fieldSet);
 
@@ -208,7 +208,10 @@ public class DescriptionController {
     @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 {
+    public Description persist(
+            @RequestBody DescriptionPersist model,
+            @Parameter(name = "fieldSet", description = SwaggerHelpers.fieldset_description, required = true) FieldSet fieldSet
+    ) throws MyApplicationException, MyForbiddenException, MyNotFoundException, InvalidApplicationException, IOException {
         logger.debug(new MapLogEntry("persisting" + Description.class.getSimpleName()).And("model", model).And("fieldSet", fieldSet));
         fieldSet = this.fieldSetExpanderService.expand(fieldSet);
         
@@ -226,7 +229,10 @@ public class DescriptionController {
     @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 {
+    public Description persistStatus(
+            @RequestBody DescriptionStatusPersist model,
+            @Parameter(name = "fieldSet", description = SwaggerHelpers.fieldset_description, required = true) FieldSet fieldSet
+    ) throws MyApplicationException, MyForbiddenException, MyNotFoundException, IOException, InvalidApplicationException {
         logger.debug(new MapLogEntry("persisting" + Description.class.getSimpleName()).And("model", model).And("fieldSet", fieldSet));
         fieldSet = this.fieldSetExpanderService.expand(fieldSet);
         
@@ -275,7 +281,9 @@ public class DescriptionController {
     @DeleteMapping("{id}")
     @Operation(summary = "Delete a description by id")
     @Transactional
-    public void delete(@PathVariable("id") UUID id) throws MyForbiddenException, InvalidApplicationException, IOException {
+    public void delete(
+            @Parameter(name = "id", description = "The id of a description to delete", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id
+    ) throws MyForbiddenException, InvalidApplicationException, IOException {
         logger.debug(new MapLogEntry("retrieving" + Description.class.getSimpleName()).And("id", id));
 
         this.descriptionService.deleteAndSave(id);
@@ -285,7 +293,10 @@ 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 {
+    public ResponseEntity<byte[]> export(
+            @Parameter(name = "id", description = "The id of a description to export", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id,
+            @Parameter(name = "type", description = "The type of the export", example = "rda", required = true) @PathVariable("type") String exportType
+    ) throws InvalidApplicationException, IOException, InvalidAlgorithmParameterException, NoSuchPaddingException, IllegalBlockSizeException, NoSuchAlgorithmException, BadPaddingException, InvalidKeyException {
         logger.debug(new MapLogEntry("exporting description"));
 
         return this.descriptionService.export(id, exportType);
@@ -295,7 +306,11 @@ public class DescriptionController {
     @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 {
+    public StorageFile uploadFieldFiles(
+            @RequestParam("file") MultipartFile file,
+            @RequestParam("model") DescriptionFieldFilePersist model,
+            @Parameter(name = "fieldSet", description = SwaggerHelpers.fieldset_description, required = true) FieldSet fieldSet
+    ) throws IOException {
         logger.debug(new MapLogEntry("uploadFieldFiles" + Description.class.getSimpleName()).And("model", model).And("fieldSet", fieldSet));
         fieldSet = this.fieldSetExpanderService.expand(fieldSet);
         
@@ -311,7 +326,10 @@ 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 {
+    public ResponseEntity<ByteArrayResource> getFieldFile(
+            @Parameter(name = "id", description = "The id of a description", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("id") UUID id,
+            @Parameter(name = "fileIid", description = "The id of the file we want to fetch", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable("fileId") UUID fileId
+    ) throws MyApplicationException, MyForbiddenException, MyNotFoundException {
         logger.debug(new MapLogEntry("get Field File" + Description.class.getSimpleName()).And("id", id).And("fileId", fileId));
 
         StorageFileEntity storageFile = this.descriptionService.getFieldFile(id, fileId);
@@ -349,7 +367,9 @@ 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 {
+    public @ResponseBody ResponseEntity<byte[]> getXml(
+            @Parameter(name = "id", description = "The id of a description to export", example = "c0c163dc-2965-45a5-9608-f76030578609", required = true) @PathVariable UUID id
+    ) throws JAXBException, ParserConfigurationException, IOException, InstantiationException, IllegalAccessException, SAXException, InvalidApplicationException {
         logger.debug(new MapLogEntry("export" + DmpBlueprint.class.getSimpleName()).And("id", id));
 
         ResponseEntity<byte[]> response = this.descriptionService.exportXml(id);
@@ -531,6 +551,11 @@ public class DescriptionController {
                         }
                         """;
 
+        static final String fieldset_description =
+                """
+                This is an object containing a list of the properties you wish to include in the response, similar to the 'project' attribute on queries.
+                """;
+
         static final String endpoint_get =
                 """