Improve Type Safety and OpenAPI Schema for PDF API Controllers and Models (#3470)

# Description of Changes

- **What was changed**  
- Updated controller methods to use strongly‐typed primitives (`int`,
`long`, `boolean`) instead of `String` for numeric and boolean
parameters, eliminating calls to `Integer.parseInt`/`Long.parseLong` and
improving null‐safety (`Boolean.TRUE.equals(...)`).
- Enhanced all API request model classes with richer Swagger/OpenAPI
annotations: added `requiredMode`, `defaultValue`, `allowableValues`,
`format`, `pattern`, and tightened schema descriptions for all fields.
- Refactored HTML form templates for “Remove Blank Pages” to include
`min`, `max`, and `step` attributes on numeric inputs, matching the
updated validation rules.

- **Why the change was made**  
- **Type safety & robustness**: Shifting from `String` to native types
prevents runtime parsing errors, simplifies controller logic, and makes
default values explicit.
- **Better API documentation & validation**: Enriching the Swagger
annotations ensures generated docs accurately reflect required fields,
default values, and permitted ranges, which improves client code
generation and developer experience.
- **Consistency across codebase**: Aligning all request models and
controllers enforces a uniform coding style and reduces bugs.

#3406

---

## Checklist

### General

- [x] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [x] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md)
(if applicable)
- [x] I have performed a self-review of my own code
- [x] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### UI Changes (if applicable)

- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [ ] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md#6-testing)
for more details.

src/main/java/stirling/software/SPDF/model/api/Email.java

@@ -4,7 +4,6 @@ import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 
 import io.swagger.v3.oas.annotations.media.Schema;
 
-
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 import lombok.NoArgsConstructor;

src/main/java/stirling/software/SPDF/model/api/GeneralFile.java

@@ -11,6 +11,9 @@ import lombok.EqualsAndHashCode;
 @EqualsAndHashCode
 public class GeneralFile {
 
-    @Schema(description = "The input file")
+    @Schema(
+            description = "The input file",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            format = "binary")
     private MultipartFile fileInput;
 }

src/main/java/stirling/software/SPDF/model/api/HandleDataRequest.java

@@ -11,9 +11,12 @@ import lombok.EqualsAndHashCode;
 @EqualsAndHashCode
 public class HandleDataRequest {
 
-    @Schema(description = "The input files")
+    @Schema(description = "The input files", requiredMode = Schema.RequiredMode.REQUIRED)
     private MultipartFile[] fileInput;
 
-    @Schema(description = "JSON String")
+    @Schema(
+            description = "JSON String",
+            defaultValue = "{}",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private String json;
 }

src/main/java/stirling/software/SPDF/model/api/ImageFile.java

@@ -10,6 +10,9 @@ import lombok.EqualsAndHashCode;
 @Data
 @EqualsAndHashCode
 public class ImageFile {
-    @Schema(description = "The input image file")
+    @Schema(
+            description = "The input image file",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            format = "binary")
     private MultipartFile fileInput;
 }

src/main/java/stirling/software/SPDF/model/api/MultiplePDFFiles.java

@@ -10,6 +10,6 @@ import lombok.EqualsAndHashCode;
 @Data
 @EqualsAndHashCode
 public class MultiplePDFFiles {
-    @Schema(description = "The input PDF files", type = "array", format = "binary")
+    @Schema(description = "The input PDF files", requiredMode = Schema.RequiredMode.REQUIRED)
     private MultipartFile[] fileInput;
 }

src/main/java/stirling/software/SPDF/model/api/PDFComparison.java

@@ -11,6 +11,7 @@ public class PDFComparison extends PDFFile {
 
     @Schema(
             description = "The comparison type, accepts Greater, Equal, Less than",
-            allowableValues = {"Greater", "Equal", "Less"})
+            allowableValues = {"Greater", "Equal", "Less"},
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private String comparator;
 }

src/main/java/stirling/software/SPDF/model/api/PDFComparisonAndCount.java

@@ -8,6 +8,6 @@ import lombok.EqualsAndHashCode;
 @Data
 @EqualsAndHashCode(callSuper = true)
 public class PDFComparisonAndCount extends PDFComparison {
-    @Schema(description = "Count")
-    private String pageCount;
+    @Schema(description = "Count", requiredMode = Schema.RequiredMode.REQUIRED, defaultValue = "0")
+    private int pageCount;
 }

src/main/java/stirling/software/SPDF/model/api/PDFExtractImagesRequest.java

@@ -11,6 +11,8 @@ public class PDFExtractImagesRequest extends PDFWithImageFormatRequest {
 
     @Schema(
             description =
-                    "Boolean to enable/disable the saving of duplicate images, true to enable duplicates")
-    private boolean allowDuplicates;
+                    "Boolean to enable/disable the saving of duplicate images, true to enable"
+                            + " duplicates",
+            defaultValue = "false")
+    private Boolean allowDuplicates;
 }

src/main/java/stirling/software/SPDF/model/api/PDFFile.java

@@ -12,6 +12,10 @@ import lombok.NoArgsConstructor;
 @NoArgsConstructor
 @EqualsAndHashCode
 public class PDFFile {
-    @Schema(description = "The input PDF file", format = "binary")
+    @Schema(
+            description = "The input PDF file",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            contentMediaType = "application/pdf",
+            format = "binary")
     private MultipartFile fileInput;
 }

src/main/java/stirling/software/SPDF/model/api/PDFWithImageFormatRequest.java

@@ -11,6 +11,8 @@ public class PDFWithImageFormatRequest extends PDFFile {
 
     @Schema(
             description = "The output image format e.g., 'png', 'jpeg', or 'gif'",
-            allowableValues = {"png", "jpeg", "gif"})
+            allowableValues = {"png", "jpeg", "gif"},
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "png")
     private String format;
 }

src/main/java/stirling/software/SPDF/model/api/PDFWithPageNums.java

@@ -21,9 +21,9 @@ public class PDFWithPageNums extends PDFFile {
             description =
                     "The pages to select, Supports ranges (e.g., '1,3,5-9'), or 'all' or functions in the"
                             + " format 'an+b' where 'a' is the multiplier of the page number 'n', and 'b' is a"
-                            + " constant (e.g., '2n+1', '3n', '6n-5')\"",
+                            + " constant (e.g., '2n+1', '3n', '6n-5')",
             defaultValue = "all",
-            requiredMode = RequiredMode.NOT_REQUIRED)
+            requiredMode = RequiredMode.REQUIRED)
     private String pageNumbers;
 
     @Hidden

src/main/java/stirling/software/SPDF/model/api/PDFWithPageSize.java

@@ -11,7 +11,9 @@ public class PDFWithPageSize extends PDFFile {
 
     @Schema(
             description =
-                    "The scale of pages in the output PDF. Acceptable values are A0-A6, LETTER, LEGAL, KEEP.",
+                    "The scale of pages in the output PDF. Acceptable values are A0-A6, LETTER,"
+                            + " LEGAL, KEEP.",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             allowableValues = {"A0", "A1", "A2", "A3", "A4", "A5", "A6", "LETTER", "LEGAL", "KEEP"})
     private String pageSize;
 }

src/main/java/stirling/software/SPDF/model/api/SplitPdfByChaptersRequest.java

@@ -8,12 +8,22 @@ import lombok.EqualsAndHashCode;
 @Data
 @EqualsAndHashCode(callSuper = false)
 public class SplitPdfByChaptersRequest extends PDFFile {
-    @Schema(description = "Whether to include Metadata or not", example = "true")
+    @Schema(
+            description = "Whether to include Metadata or not",
+            defaultValue = "true",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private Boolean includeMetadata;
 
-    @Schema(description = "Whether to allow duplicates or not", example = "true")
+    @Schema(
+            description = "Whether to allow duplicates or not",
+            defaultValue = "true",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private Boolean allowDuplicates;
 
-    @Schema(description = "Maximum bookmark level required", example = "2")
+    @Schema(
+            description = "Maximum bookmark level required",
+            minimum = "0",
+            defaultValue = "2",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private Integer bookmarkLevel;
 }

src/main/java/stirling/software/SPDF/model/api/SplitPdfBySectionsRequest.java

@@ -8,12 +8,23 @@ import lombok.EqualsAndHashCode;
 @Data
 @EqualsAndHashCode(callSuper = true)
 public class SplitPdfBySectionsRequest extends PDFFile {
-    @Schema(description = "Number of horizontal divisions for each PDF page", example = "2")
+    @Schema(
+            description = "Number of horizontal divisions for each PDF page",
+            defaultValue = "0",
+            minimum = "0",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private int horizontalDivisions;
 
-    @Schema(description = "Number of vertical divisions for each PDF page", example = "2")
+    @Schema(
+            description = "Number of vertical divisions for each PDF page",
+            defaultValue = "1",
+            minimum = "0",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private int verticalDivisions;
 
-    @Schema(description = "Merge the split documents into a single PDF", example = "true")
-    private boolean merge;
+    @Schema(
+            description = "Merge the split documents into a single PDF",
+            defaultValue = "true",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Boolean merge;
 }

src/main/java/stirling/software/SPDF/model/api/converters/ConvertPDFToMarkdown.java

@@ -23,9 +23,9 @@ public class ConvertPDFToMarkdown {
             summary = "Convert PDF to Markdown",
             description =
                     "This endpoint converts a PDF file to Markdown format. Input:PDF Output:Markdown Type:SISO")
-    public ResponseEntity<byte[]> processPdfToMarkdown(@ModelAttribute PDFFile request)
+    public ResponseEntity<byte[]> processPdfToMarkdown(@ModelAttribute PDFFile file)
             throws Exception {
-        MultipartFile inputFile = request.getFileInput();
+        MultipartFile inputFile = file.getFileInput();
         PDFToFile pdfToFile = new PDFToFile();
         return pdfToFile.processPdfToMarkdown(inputFile);
     }

src/main/java/stirling/software/SPDF/model/api/converters/ConvertToImageRequest.java

@@ -5,33 +5,38 @@ import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 
-import stirling.software.SPDF.model.api.PDFFile;
+import stirling.software.SPDF.model.api.PDFWithPageNums;
 
 @Data
 @EqualsAndHashCode(callSuper = true)
-public class ConvertToImageRequest extends PDFFile {
+public class ConvertToImageRequest extends PDFWithPageNums {
 
     @Schema(
             description = "The output image format",
-            allowableValues = {"png", "jpeg", "jpg", "gif", "webp"})
+            defaultValue = "png",
+            allowableValues = {"png", "jpeg", "jpg", "gif", "webp"},
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private String imageFormat;
 
     @Schema(
             description =
-                    "Choose between a single image containing all pages or separate images for each page",
-            allowableValues = {"single", "multiple"})
+                    "Choose between a single image containing all pages or separate images for each"
+                            + " page",
+            defaultValue = "multiple",
+            allowableValues = {"single", "multiple"},
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private String singleOrMultiple;
 
-    @Schema(
-            description =
-                    "The pages to select, Supports ranges (e.g., '1,3,5-9'), or 'all' or functions in the format 'an+b' where 'a' is the multiplier of the page number 'n', and 'b' is a constant (e.g., '2n+1', '3n', '6n-5')\"")
-    private String pageNumbers;
-
     @Schema(
             description = "The color type of the output image(s)",
-            allowableValues = {"color", "greyscale", "blackwhite"})
+            defaultValue = "color",
+            allowableValues = {"color", "greyscale", "blackwhite"},
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private String colorType;
 
-    @Schema(description = "The DPI (dots per inch) for the output image(s)")
-    private String dpi;
+    @Schema(
+            description = "The DPI (dots per inch) for the output image(s)",
+            defaultValue = "300",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Integer dpi;
 }

src/main/java/stirling/software/SPDF/model/api/converters/ConvertToPdfRequest.java

@@ -11,21 +11,28 @@ import lombok.EqualsAndHashCode;
 @EqualsAndHashCode
 public class ConvertToPdfRequest {
 
-    @Schema(description = "The input images to be converted to a PDF file")
+    @Schema(
+            description = "The input images to be converted to a PDF file",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private MultipartFile[] fileInput;
 
     @Schema(
             description = "Option to determine how the image will fit onto the page",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "fillPage",
             allowableValues = {"fillPage", "fitDocumentToImage", "maintainAspectRatio"})
     private String fitOption;
 
     @Schema(
             description = "The color type of the output image(s)",
+            defaultValue = "color",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             allowableValues = {"color", "greyscale", "blackwhite"})
     private String colorType;
 
     @Schema(
             description = "Whether to automatically rotate the images to better fit the PDF page",
-            example = "true")
-    private boolean autoRotate;
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "false")
+    private Boolean autoRotate;
 }

src/main/java/stirling/software/SPDF/model/api/converters/HTMLToPdfRequest.java

@@ -13,6 +13,7 @@ public class HTMLToPdfRequest extends PDFFile {
 
     @Schema(
             description = "Zoom level for displaying the website. Default is '1'.",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             defaultValue = "1")
     private float zoom;
 }

src/main/java/stirling/software/SPDF/model/api/converters/PdfToBookRequest.java

@@ -13,6 +13,7 @@ public class PdfToBookRequest extends PDFFile {
 
     @Schema(
             description = "The output Ebook format",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             allowableValues = {
                 "epub", "mobi", "azw3", "docx", "rtf", "txt", "html", "lit", "fb2", "pdb", "lrf"
             })

src/main/java/stirling/software/SPDF/model/api/converters/PdfToPdfARequest.java

@@ -13,6 +13,7 @@ public class PdfToPdfARequest extends PDFFile {
 
     @Schema(
             description = "The output PDF/A type",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             allowableValues = {"pdfa", "pdfa-1"})
     private String outputFormat;
 }

src/main/java/stirling/software/SPDF/model/api/converters/PdfToPresentationRequest.java

@@ -13,6 +13,7 @@ public class PdfToPresentationRequest extends PDFFile {
 
     @Schema(
             description = "The output Presentation format",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             allowableValues = {"ppt", "pptx", "odp"})
     private String outputFormat;
 }

src/main/java/stirling/software/SPDF/model/api/converters/PdfToTextOrRTFRequest.java

@@ -13,6 +13,7 @@ public class PdfToTextOrRTFRequest extends PDFFile {
 
     @Schema(
             description = "The output Text or RTF format",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             allowableValues = {"rtf", "txt"})
     private String outputFormat;
 }

src/main/java/stirling/software/SPDF/model/api/converters/PdfToWordRequest.java

@@ -13,6 +13,7 @@ public class PdfToWordRequest extends PDFFile {
 
     @Schema(
             description = "The output Word document format",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             allowableValues = {"doc", "docx", "odt"})
     private String outputFormat;
 }

src/main/java/stirling/software/SPDF/model/api/filter/ContainsTextRequest.java

@@ -11,6 +11,9 @@ import stirling.software.SPDF.model.api.PDFWithPageNums;
 @EqualsAndHashCode(callSuper = true)
 public class ContainsTextRequest extends PDFWithPageNums {
 
-    @Schema(description = "The text to check for", requiredMode = Schema.RequiredMode.REQUIRED)
+    @Schema(
+            description = "The text to check for",
+            defaultValue = "text",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private String text;
 }

src/main/java/stirling/software/SPDF/model/api/filter/FileSizeRequest.java

@@ -11,6 +11,9 @@ import stirling.software.SPDF.model.api.PDFComparison;
 @EqualsAndHashCode(callSuper = true)
 public class FileSizeRequest extends PDFComparison {
 
-    @Schema(description = "File Size", requiredMode = Schema.RequiredMode.REQUIRED)
-    private String fileSize;
+    @Schema(
+            description = "Size of the file in bytes",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "0")
+    private long fileSize;
 }

src/main/java/stirling/software/SPDF/model/api/filter/PageRotationRequest.java

@@ -11,6 +11,9 @@ import stirling.software.SPDF.model.api.PDFComparison;
 @EqualsAndHashCode(callSuper = true)
 public class PageRotationRequest extends PDFComparison {
 
-    @Schema(description = "Rotation in degrees", requiredMode = Schema.RequiredMode.REQUIRED)
+    @Schema(
+            description = "Rotation in degrees",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "0")
     private int rotation;
 }

src/main/java/stirling/software/SPDF/model/api/filter/PageSizeRequest.java

@@ -11,6 +11,10 @@ import stirling.software.SPDF.model.api.PDFComparison;
 @EqualsAndHashCode(callSuper = true)
 public class PageSizeRequest extends PDFComparison {
 
-    @Schema(description = "Standard Page Size", requiredMode = Schema.RequiredMode.REQUIRED)
+    @Schema(
+            description = "Standard Page Size",
+            allowableValues = {"A0", "A1", "A2", "A3", "A4", "A5", "A6", "LETTER", "LEGAL"},
+            defaultValue = "A4",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private String standardPageSize;
 }

src/main/java/stirling/software/SPDF/model/api/general/MergeMultiplePagesRequest.java

@@ -13,10 +13,12 @@ public class MergeMultiplePagesRequest extends PDFFile {
 
     @Schema(
             description = "The number of pages to fit onto a single sheet in the output PDF.",
-            type = "integer",
+            type = "number",
+            defaultValue = "2",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             allowableValues = {"2", "3", "4", "9", "16"})
     private int pagesPerSheet;
 
     @Schema(description = "Boolean for if you wish to add border around the pages")
-    private boolean addBorder;
+    private Boolean addBorder;
 }

src/main/java/stirling/software/SPDF/model/api/general/MergePdfsRequest.java

@@ -20,12 +20,16 @@ public class MergePdfsRequest extends MultiplePDFFiles {
                 "byDateCreated",
                 "byPDFTitle"
             },
+            requiredMode = Schema.RequiredMode.REQUIRED,
             defaultValue = "orderProvided")
     private String sortType = "orderProvided";
 
     @Schema(
             description =
-                    "Flag indicating whether to remove certification signatures from the merged PDF. If true, all certification signatures will be removed from the final merged document.",
-            example = "true")
-    private boolean isRemoveCertSign;
+                    "Flag indicating whether to remove certification signatures from the merged"
+                            + " PDF. If true, all certification signatures will be removed from the"
+                            + " final merged document.",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "true")
+    private Boolean removeCertSign;
 }

src/main/java/stirling/software/SPDF/model/api/general/OverlayPdfsRequest.java

@@ -15,21 +15,32 @@ public class OverlayPdfsRequest extends PDFFile {
 
     @Schema(
             description =
-                    "An array of PDF files to be used as overlays on the base PDF. The order in these files is applied based on the selected mode.")
+                    "An array of PDF files to be used as overlays on the base PDF. The order in"
+                            + " these files is applied based on the selected mode.",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private MultipartFile[] overlayFiles;
 
     @Schema(
             description =
-                    "The mode of overlaying: 'SequentialOverlay' for sequential application, 'InterleavedOverlay' for round-robin application, 'FixedRepeatOverlay' for fixed repetition based on provided counts",
+                    "The mode of overlaying: 'SequentialOverlay' for sequential application,"
+                            + " 'InterleavedOverlay' for round-robin application, 'FixedRepeatOverlay'"
+                            + " for fixed repetition based on provided counts",
+            allowableValues = {"SequentialOverlay", "InterleavedOverlay", "FixedRepeatOverlay"},
             requiredMode = Schema.RequiredMode.REQUIRED)
     private String overlayMode;
 
     @Schema(
             description =
-                    "An array of integers specifying the number of times each corresponding overlay file should be applied in the 'FixedRepeatOverlay' mode. This should match the length of the overlayFiles array.",
+                    "An array of integers specifying the number of times each corresponding overlay"
+                            + " file should be applied in the 'FixedRepeatOverlay' mode. This should"
+                            + " match the length of the overlayFiles array.",
             requiredMode = Schema.RequiredMode.NOT_REQUIRED)
     private int[] counts;
 
-    @Schema(description = "Overlay position 0 is Foregound, 1 is Background")
+    @Schema(
+            description = "Overlay position 0 is Foregound, 1 is Background",
+            allowableValues = {"0", "1"},
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            type = "number")
     private int overlayPosition;
 }

src/main/java/stirling/software/SPDF/model/api/general/RotatePDFRequest.java

@@ -14,6 +14,8 @@ public class RotatePDFRequest extends PDFFile {
     @Schema(
             description =
                     "The angle by which to rotate the PDF file. This should be a multiple of 90.",
-            example = "90")
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            allowableValues = {"0", "90", "180", "270"},
+            defaultValue = "90")
     private Integer angle;
 }

src/main/java/stirling/software/SPDF/model/api/general/ScalePagesRequest.java

@@ -12,7 +12,11 @@ import stirling.software.SPDF.model.api.PDFWithPageSize;
 public class ScalePagesRequest extends PDFWithPageSize {
 
     @Schema(
+            minimum = "0",
+            defaultValue = "1",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             description =
-                    "The scale of the content on the pages of the output PDF. Acceptable values are floats.")
+                    "The scale of the content on the pages of the output PDF. Acceptable values are"
+                            + " floats.")
     private float scaleFactor;
 }

src/main/java/stirling/software/SPDF/model/api/misc/AddPageNumbersRequest.java

@@ -22,6 +22,7 @@ public class AddPageNumbersRequest extends PDFWithPageNums {
     @Schema(
             description = "Font size for page numbers",
             minimum = "1",
+            defaultValue = "12",
             requiredMode = RequiredMode.REQUIRED)
     private float fontSize;
 
@@ -33,15 +34,18 @@ public class AddPageNumbersRequest extends PDFWithPageNums {
 
     @Schema(
             description =
-                    "Position: 1-9 representing positions on the page (1=top-left, 5=center, 9=bottom-right)",
-            minimum = "1",
-            maximum = "9",
+                    "Position: 1-9 representing positions on the page (1=top-left, 2=top-center,"
+                            + " 3=top-right, 4=middle-left, 5=middle-center, 6=middle-right,"
+                            + " 7=bottom-left, 8=bottom-center, 9=bottom-right)",
+            allowableValues = {"1", "2", "3", "4", "5", "6", "7", "8", "9"},
+            defaultValue = "8",
             requiredMode = RequiredMode.REQUIRED)
     private int position;
 
     @Schema(
             description = "Starting number for page numbering",
             minimum = "1",
+            defaultValue = "1",
             requiredMode = RequiredMode.REQUIRED)
     private int startingNumber;
 
@@ -53,7 +57,8 @@ public class AddPageNumbersRequest extends PDFWithPageNums {
 
     @Schema(
             description =
-                    "Custom text pattern. Available variables: {n}=current page number, {total}=total pages, {filename}=original filename",
+                    "Custom text pattern. Available variables: {n}=current page number,"
+                            + " {total}=total pages, {filename}=original filename",
             example = "Page {n} of {total}",
             defaultValue = "{n}",
             requiredMode = RequiredMode.NOT_REQUIRED)

src/main/java/stirling/software/SPDF/model/api/misc/AddStampRequest.java

@@ -19,51 +19,69 @@ public class AddStampRequest extends PDFWithPageNums {
             requiredMode = Schema.RequiredMode.REQUIRED)
     private String stampType;
 
-    @Schema(description = "The stamp text")
+    @Schema(description = "The stamp text", defaultValue = "Stirling Software")
     private String stampText;
 
     @Schema(description = "The stamp image")
     private MultipartFile stampImage;
 
     @Schema(
-            description = "The selected alphabet",
+            description = "The selected alphabet of the stamp text",
             allowableValues = {"roman", "arabic", "japanese", "korean", "chinese"},
             defaultValue = "roman")
     private String alphabet = "roman";
 
-    @Schema(description = "The font size of the stamp text", example = "30")
-    private float fontSize = 30;
+    @Schema(
+            description = "The font size of the stamp text and image",
+            defaultValue = "30",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private float fontSize;
 
-    @Schema(description = "The rotation of the stamp in degrees", example = "0")
-    private float rotation = 0;
+    @Schema(
+            description = "The rotation of the stamp in degrees",
+            defaultValue = "0",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private float rotation;
 
-    @Schema(description = "The opacity of the stamp (0.0 - 1.0)", example = "0.5")
+    @Schema(
+            description = "The opacity of the stamp (0.0 - 1.0)",
+            defaultValue = "0.5",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private float opacity;
 
     @Schema(
             description =
-                    "Position for stamp placement based on a 1-9 grid (1: bottom-left, 2: bottom-center, ..., 9: top-right)",
-            example = "1")
+                    "Position for stamp placement based on a 1-9 grid (1: bottom-left, 2: bottom-center,"
+                            + " 3: bottom-right, 4: middle-left, 5: middle-center, 6: middle-right,"
+                            + " 7: top-left, 8: top-center, 9: top-right)",
+            allowableValues = {"1", "2", "3", "4", "5", "6", "7", "8", "9"},
+            defaultValue = "5",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private int position;
 
     @Schema(
             description =
-                    "Override X coordinate for stamp placement. If set, it will override the position-based calculation. Negative value means no override.",
-            example = "-1")
-    private float overrideX = -1; // Default to -1 indicating no override
+                    "Override X coordinate for stamp placement. If set, it will override the"
+                            + " position-based calculation. Negative value means no override.",
+            defaultValue = "-1",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private float overrideX; // Default to -1 indicating no override
 
     @Schema(
             description =
-                    "Override Y coordinate for stamp placement. If set, it will override the position-based calculation. Negative value means no override.",
-            example = "-1")
-    private float overrideY = -1; // Default to -1 indicating no override
+                    "Override Y coordinate for stamp placement. If set, it will override the"
+                            + " position-based calculation. Negative value means no override.",
+            defaultValue = "-1",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private float overrideY; // Default to -1 indicating no override
 
     @Schema(
             description = "Specifies the margin size for the stamp.",
             allowableValues = {"small", "medium", "large", "x-large"},
-            defaultValue = "medium")
-    private String customMargin = "medium";
+            defaultValue = "medium",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private String customMargin;
 
-    @Schema(description = "The color for stamp", defaultValue = "#d3d3d3")
-    private String customColor = "#d3d3d3";
+    @Schema(description = "The color of the stamp text", defaultValue = "#d3d3d3")
+    private String customColor;
 }

src/main/java/stirling/software/SPDF/model/api/misc/AutoSplitPdfRequest.java

@@ -16,5 +16,5 @@ public class AutoSplitPdfRequest extends PDFFile {
                     "Flag indicating if the duplex mode is active, where the page after the divider also gets removed.",
             requiredMode = Schema.RequiredMode.NOT_REQUIRED,
             defaultValue = "false")
-    private boolean duplexMode;
+    private Boolean duplexMode;
 }

src/main/java/stirling/software/SPDF/model/api/misc/ExtractHeaderRequest.java

@@ -16,5 +16,5 @@ public class ExtractHeaderRequest extends PDFFile {
                     "Flag indicating whether to use the first text as a fallback if no suitable title is found. Defaults to false.",
             requiredMode = Schema.RequiredMode.NOT_REQUIRED,
             defaultValue = "false")
-    private boolean useFirstTextAsFallback;
+    private Boolean useFirstTextAsFallback;
 }

src/main/java/stirling/software/SPDF/model/api/misc/ExtractImageScansRequest.java

@@ -12,36 +12,37 @@ import lombok.EqualsAndHashCode;
 public class ExtractImageScansRequest {
     @Schema(
             description = "The input file containing image scans",
-            requiredMode = Schema.RequiredMode.REQUIRED)
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            format = "binary")
     private MultipartFile fileInput;
 
     @Schema(
             description = "The angle threshold for the image scan extraction",
-            defaultValue = "5",
-            example = "5")
-    private int angleThreshold = 5;
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "5")
+    private int angleThreshold;
 
     @Schema(
             description = "The tolerance for the image scan extraction",
-            defaultValue = "20",
-            example = "20")
-    private int tolerance = 20;
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "20")
+    private int tolerance;
 
     @Schema(
             description = "The minimum area for the image scan extraction",
-            defaultValue = "8000",
-            example = "8000")
-    private int minArea = 8000;
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "8000")
+    private int minArea;
 
     @Schema(
             description = "The minimum contour area for the image scan extraction",
-            defaultValue = "500",
-            example = "500")
-    private int minContourArea = 500;
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "500")
+    private int minContourArea;
 
     @Schema(
             description = "The border size for the image scan extraction",
-            defaultValue = "1",
-            example = "1")
-    private int borderSize = 1;
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "1")
+    private int borderSize;
 }

src/main/java/stirling/software/SPDF/model/api/misc/FlattenRequest.java

@@ -13,6 +13,9 @@ public class FlattenRequest extends PDFFile {
 
     @Schema(
             description =
-                    "True to flatten only the forms, false to flatten full PDF (Convert page to image)")
+                    "True to flatten only the forms, false to flatten full PDF (Convert page to"
+                            + " image)",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "false")
     private Boolean flattenOnlyForms;
 }

src/main/java/stirling/software/SPDF/model/api/misc/MetadataRequest.java

@@ -13,38 +13,72 @@ import stirling.software.SPDF.model.api.PDFFile;
 @EqualsAndHashCode(callSuper = true)
 public class MetadataRequest extends PDFFile {
 
-    @Schema(description = "Delete all metadata if set to true")
-    private boolean deleteAll;
+    @Schema(
+            description = "Delete all metadata if set to true",
+            defaultValue = "false",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Boolean deleteAll;
 
-    @Schema(description = "The author of the document")
+    @Schema(
+            description = "The author of the document",
+            defaultValue = "author",
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED)
     private String author;
 
-    @Schema(description = "The creation date of the document (format: yyyy/MM/dd HH:mm:ss)")
+    @Schema(
+            description = "The creation date of the document (format: yyyy/MM/dd HH:mm:ss)",
+            pattern = "yyyy/MM/dd HH:mm:ss",
+            defaultValue = "2023/10/01 12:00:00",
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED)
     private String creationDate;
 
-    @Schema(description = "The creator of the document")
+    @Schema(
+            description = "The creator of the document",
+            defaultValue = "creator",
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED)
     private String creator;
 
-    @Schema(description = "The keywords for the document")
+    @Schema(
+            description = "The keywords for the document",
+            defaultValue = "keywords",
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED)
     private String keywords;
 
-    @Schema(description = "The modification date of the document (format: yyyy/MM/dd HH:mm:ss)")
+    @Schema(
+            description = "The modification date of the document (format: yyyy/MM/dd HH:mm:ss)",
+            pattern = "yyyy/MM/dd HH:mm:ss",
+            defaultValue = "2023/10/01 12:00:00",
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED)
     private String modificationDate;
 
-    @Schema(description = "The producer of the document")
+    @Schema(
+            description = "The producer of the document",
+            defaultValue = "producer",
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED)
     private String producer;
 
-    @Schema(description = "The subject of the document")
+    @Schema(
+            description = "The subject of the document",
+            defaultValue = "subject",
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED)
     private String subject;
 
-    @Schema(description = "The title of the document")
+    @Schema(
+            description = "The title of the document",
+            defaultValue = "title",
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED)
     private String title;
 
-    @Schema(description = "The trapped status of the document")
+    @Schema(
+            description = "The trapped status of the document",
+            defaultValue = "False",
+            allowableValues = {"True", "False", "Unknown"},
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED)
     private String trapped;
 
     @Schema(
             description =
-                    "Map list of key and value of custom parameters. Note these must start with customKey and customValue if they are non-standard")
+                    "Map list of key and value of custom parameters. Note these must start with"
+                            + " customKey and customValue if they are non-standard")
     private Map<String, String> allRequestParams;
 }

src/main/java/stirling/software/SPDF/model/api/misc/OptimizePdfRequest.java

@@ -13,30 +13,36 @@ public class OptimizePdfRequest extends PDFFile {
 
     @Schema(
             description =
-                    "The level of optimization to apply to the PDF file. Higher values indicate greater compression but may reduce quality.",
+                    "The level of optimization to apply to the PDF file. Higher values indicate"
+                            + " greater compression but may reduce quality.",
+            defaultValue = "5",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             allowableValues = {"1", "2", "3", "4", "5", "6", "7", "8", "9"})
     private Integer optimizeLevel;
 
-    @Schema(description = "The expected output size, e.g. '100MB', '25KB', etc.")
+    @Schema(
+            description = "The expected output size, e.g. '100MB', '25KB', etc.",
+            defaultValue = "25KB",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private String expectedOutputSize;
 
     @Schema(
             description = "Whether to linearize the PDF for faster web viewing. Default is false.",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             defaultValue = "false")
     private Boolean linearize = false;
 
     @Schema(
             description =
-                    "Whether to normalize the PDF content for better compatibility. Default is false.",
+                    "Whether to normalize the PDF content for better compatibility. Default is"
+                            + " false.",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             defaultValue = "false")
     private Boolean normalize = false;
 
     @Schema(
             description = "Whether to convert the PDF to grayscale. Default is false.",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             defaultValue = "false")
     private Boolean grayscale = false;
-
-    public Boolean getGrayscale() {
-        return grayscale;
-    }
 }

src/main/java/stirling/software/SPDF/model/api/misc/OverlayImageRequest.java

@@ -13,21 +13,27 @@ import stirling.software.SPDF.model.api.PDFFile;
 @EqualsAndHashCode(callSuper = true)
 public class OverlayImageRequest extends PDFFile {
 
-    @Schema(description = "The image file to be overlaid onto the PDF.")
+    @Schema(
+            description = "The image file to be overlaid onto the PDF.",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            format = "binary")
     private MultipartFile imageFile;
 
     @Schema(
             description = "The x-coordinate at which to place the top-left corner of the image.",
-            example = "0")
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "0")
     private float x;
 
     @Schema(
             description = "The y-coordinate at which to place the top-left corner of the image.",
-            example = "0")
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "0")
     private float y;
 
     @Schema(
             description = "Whether to overlay the image onto every page of the PDF.",
-            example = "false")
-    private boolean everyPage;
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "false")
+    private Boolean everyPage;
 }

src/main/java/stirling/software/SPDF/model/api/misc/ProcessPdfWithOcrRequest.java

@@ -13,16 +13,21 @@ import stirling.software.SPDF.model.api.PDFFile;
 @EqualsAndHashCode(callSuper = true)
 public class ProcessPdfWithOcrRequest extends PDFFile {
 
-    @Schema(description = "List of languages to use in OCR processing")
+    @Schema(
+            description = "List of languages to use in OCR processing, e.g., 'eng', 'deu'",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "[\"eng\"]")
     private List<String> languages;
 
     @Schema(
             description = "Specify the OCR type, e.g., 'skip-text', 'force-ocr', or 'Normal'",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             allowableValues = {"skip-text", "force-ocr", "Normal"})
     private String ocrType;
 
     @Schema(
             description = "Specify the OCR render type, either 'hocr' or 'sandwich'",
+            requiredMode = Schema.RequiredMode.REQUIRED,
             allowableValues = {"hocr", "sandwich"},
             defaultValue = "hocr")
     private String ocrRenderType = "hocr";

src/main/java/stirling/software/SPDF/model/api/misc/RemoveBlankPagesRequest.java

@@ -13,13 +13,17 @@ public class RemoveBlankPagesRequest extends PDFFile {
 
     @Schema(
             description = "The threshold value to determine blank pages",
-            example = "10",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            minimum = "0",
+            maximum = "255",
             defaultValue = "10")
-    private int threshold = 10;
+    private int threshold;
 
     @Schema(
             description = "The percentage of white color on a page to consider it as blank",
-            example = "99.9",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            minimum = "0.1",
+            maximum = "100",
             defaultValue = "99.9")
-    private float whitePercent = 99.9f;
+    private float whitePercent;
 }

src/main/java/stirling/software/SPDF/model/api/misc/ReplaceAndInvertColorRequest.java

@@ -13,12 +13,16 @@ public class ReplaceAndInvertColorRequest extends PDFFile {
 
     @Schema(
             description = "Replace and Invert color options of a pdf.",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "HIGH_CONTRAST_COLOR",
             allowableValues = {"HIGH_CONTRAST_COLOR", "CUSTOM_COLOR", "FULL_INVERSION"})
     private ReplaceAndInvert replaceAndInvertOption;
 
     @Schema(
             description =
                     "If HIGH_CONTRAST_COLOR option selected, then pick the default color option for text and background.",
+            requiredMode = Schema.RequiredMode.REQUIRED,
+            defaultValue = "WHITE_TEXT_ON_BLACK",
             allowableValues = {
                 "WHITE_TEXT_ON_BLACK",
                 "BLACK_TEXT_ON_WHITE",

src/main/java/stirling/software/SPDF/model/api/security/AddPasswordRequest.java

@@ -13,45 +13,50 @@ public class AddPasswordRequest extends PDFFile {
 
     @Schema(
             description =
-                    "The owner password to be added to the PDF file (Restricts what can be done with the document once it is opened)",
-            defaultValue = "")
+                    "The owner password to be added to the PDF file (Restricts what can be done"
+                            + " with the document once it is opened)",
+            format = "password")
     private String ownerPassword;
 
     @Schema(
             description =
-                    "The password to be added to the PDF file (Restricts the opening of the document itself.)",
-            defaultValue = "")
+                    "The password to be added to the PDF file (Restricts the opening of the"
+                            + " document itself.)",
+            format = "password")
     private String password;
 
     @Schema(
             description = "The length of the encryption key",
             allowableValues = {"40", "128", "256"},
-            defaultValue = "256")
+            defaultValue = "256",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private int keyLength = 256;
 
-    @Schema(description = "Whether document assembly is prevented", example = "false")
-    private boolean preventAssembly;
+    @Schema(description = "Whether document assembly is prevented", defaultValue = "false")
+    private Boolean preventAssembly;
 
-    @Schema(description = "Whether content extraction is prevented", example = "false")
-    private boolean preventExtractContent;
+    @Schema(description = "Whether content extraction is prevented", defaultValue = "false")
+    private Boolean preventExtractContent;
 
     @Schema(
             description = "Whether content extraction for accessibility is prevented",
-            example = "false")
-    private boolean preventExtractForAccessibility;
+            defaultValue = "false")
+    private Boolean preventExtractForAccessibility;
 
-    @Schema(description = "Whether form filling is prevented", example = "false")
-    private boolean preventFillInForm;
+    @Schema(description = "Whether form filling is prevented", defaultValue = "false")
+    private Boolean preventFillInForm;
 
-    @Schema(description = "Whether document modification is prevented", example = "false")
-    private boolean preventModify;
+    @Schema(description = "Whether document modification is prevented", defaultValue = "false")
+    private Boolean preventModify;
 
-    @Schema(description = "Whether modification of annotations is prevented", example = "false")
-    private boolean preventModifyAnnotations;
+    @Schema(
+            description = "Whether modification of annotations is prevented",
+            defaultValue = "false")
+    private Boolean preventModifyAnnotations;
 
-    @Schema(description = "Whether printing of the document is prevented", example = "false")
-    private boolean preventPrinting;
+    @Schema(description = "Whether printing of the document is prevented", defaultValue = "false")
+    private Boolean preventPrinting;
 
-    @Schema(description = "Whether faithful printing is prevented", example = "false")
-    private boolean preventPrintingFaithful;
+    @Schema(description = "Whether faithful printing is prevented", defaultValue = "false")
+    private Boolean preventPrintingFaithful;
 }

src/main/java/stirling/software/SPDF/model/api/security/AddWatermarkRequest.java

@@ -19,7 +19,7 @@ public class AddWatermarkRequest extends PDFFile {
             requiredMode = Schema.RequiredMode.REQUIRED)
     private String watermarkType;
 
-    @Schema(description = "The watermark text")
+    @Schema(description = "The watermark text", defaultValue = "Stirling Software")
     private String watermarkText;
 
     @Schema(description = "The watermark image")
@@ -29,26 +29,29 @@ public class AddWatermarkRequest extends PDFFile {
             description = "The selected alphabet",
             allowableValues = {"roman", "arabic", "japanese", "korean", "chinese"},
             defaultValue = "roman")
-    private String alphabet = "roman";
+    private String alphabet;
 
-    @Schema(description = "The font size of the watermark text", example = "30")
-    private float fontSize = 30;
+    @Schema(description = "The font size of the watermark text", defaultValue = "30")
+    private float fontSize;
 
-    @Schema(description = "The rotation of the watermark in degrees", example = "0")
-    private float rotation = 0;
+    @Schema(description = "The rotation of the watermark in degrees", defaultValue = "0")
+    private float rotation;
 
-    @Schema(description = "The opacity of the watermark (0.0 - 1.0)", example = "0.5")
+    @Schema(description = "The opacity of the watermark (0.0 - 1.0)", defaultValue = "0.5")
     private float opacity;
 
-    @Schema(description = "The width spacer between watermark elements", example = "50")
+    @Schema(description = "The width spacer between watermark elements", defaultValue = "50")
     private int widthSpacer;
 
-    @Schema(description = "The height spacer between watermark elements", example = "50")
+    @Schema(description = "The height spacer between watermark elements", defaultValue = "50")
     private int heightSpacer;
 
     @Schema(description = "The color for watermark", defaultValue = "#d3d3d3")
-    private String customColor = "#d3d3d3";
+    private String customColor;
 
-    @Schema(description = "Convert the redacted PDF to an image", defaultValue = "false")
-    private boolean convertPDFToImage;
+    @Schema(
+            description = "Convert the redacted PDF to an image",
+            defaultValue = "false",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Boolean convertPDFToImage;
 }

src/main/java/stirling/software/SPDF/model/api/security/ManualRedactPdfRequest.java

@@ -12,12 +12,20 @@ import stirling.software.SPDF.model.api.PDFWithPageNums;
 @Data
 @EqualsAndHashCode(callSuper = true)
 public class ManualRedactPdfRequest extends PDFWithPageNums {
-    @Schema(description = "A list of areas that should be redacted")
+    @Schema(
+            description = "A list of areas that should be redacted",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private List<RedactionArea> redactions;
 
-    @Schema(description = "Convert the redacted PDF to an image", defaultValue = "false")
-    private boolean convertPDFToImage;
+    @Schema(
+            description = "Convert the redacted PDF to an image",
+            defaultValue = "false",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Boolean convertPDFToImage;
 
-    @Schema(description = "The color used to fully redact certain pages")
+    @Schema(
+            description = "The color used to fully redact certain pages",
+            defaultValue = "#000000",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private String pageRedactionColor;
 }

src/main/java/stirling/software/SPDF/model/api/security/PDFPasswordRequest.java

@@ -13,6 +13,7 @@ public class PDFPasswordRequest extends PDFFile {
 
     @Schema(
             description = "The password of the PDF file",
-            requiredMode = Schema.RequiredMode.REQUIRED)
+            format = "password",
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED)
     private String password;
 }

src/main/java/stirling/software/SPDF/model/api/security/RedactPdfRequest.java

@@ -13,22 +13,37 @@ public class RedactPdfRequest extends PDFFile {
 
     @Schema(
             description = "List of text to redact from the PDF",
-            type = "string",
+            defaultValue = "text,text2",
             requiredMode = Schema.RequiredMode.REQUIRED)
     private String listOfText;
 
-    @Schema(description = "Whether to use regex for the listOfText", defaultValue = "false")
-    private boolean useRegex;
+    @Schema(
+            description = "Whether to use regex for the listOfText",
+            defaultValue = "false",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Boolean useRegex;
 
-    @Schema(description = "Whether to use whole word search", defaultValue = "false")
-    private boolean wholeWordSearch;
+    @Schema(
+            description = "Whether to use whole word search",
+            defaultValue = "false",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Boolean wholeWordSearch;
 
-    @Schema(description = "Hexadecimal color code for redaction, e.g. #FF0000 or 000000", defaultValue = "#000000")
-    private String redactColor = "#000000";
+    @Schema(
+            description = "The color for redaction",
+            defaultValue = "#000000",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private String redactColor;
 
-    @Schema(description = "Custom padding for redaction", type = "number")
+    @Schema(
+            description = "Custom padding for redaction",
+            type = "number",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private float customPadding;
 
-    @Schema(description = "Convert the redacted PDF to an image", defaultValue = "false")
-    private boolean convertPDFToImage;
+    @Schema(
+            description = "Convert the redacted PDF to an image",
+            defaultValue = "false",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Boolean convertPDFToImage;
 }

src/main/java/stirling/software/SPDF/model/api/security/RedactionArea.java

@@ -3,8 +3,10 @@ package stirling.software.SPDF.model.api.security;
 import io.swagger.v3.oas.annotations.media.Schema;
 
 import lombok.Data;
+import lombok.EqualsAndHashCode;
 
 @Data
+@EqualsAndHashCode
 public class RedactionArea {
     @Schema(description = "The left edge point of the area to be redacted.")
     private Double x;

src/main/java/stirling/software/SPDF/model/api/security/SanitizePdfRequest.java

@@ -11,21 +11,39 @@ import stirling.software.SPDF.model.api.PDFFile;
 @EqualsAndHashCode(callSuper = true)
 public class SanitizePdfRequest extends PDFFile {
 
-    @Schema(description = "Remove JavaScript actions from the PDF", defaultValue = "false")
-    private boolean removeJavaScript;
+    @Schema(
+            description = "Remove JavaScript actions from the PDF",
+            defaultValue = "true",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Boolean removeJavaScript;
 
-    @Schema(description = "Remove embedded files from the PDF", defaultValue = "false")
-    private boolean removeEmbeddedFiles;
+    @Schema(
+            description = "Remove embedded files from the PDF",
+            defaultValue = "true",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Boolean removeEmbeddedFiles;
 
-    @Schema(description = "Remove XMP metadata from the PDF", defaultValue = "false")
-    private boolean removeXMPMetadata;
+    @Schema(
+            description = "Remove XMP metadata from the PDF",
+            defaultValue = "false",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Boolean removeXMPMetadata;
 
-    @Schema(description = "Remove document info metadata from the PDF", defaultValue = "false")
-    private boolean removeMetadata;
+    @Schema(
+            description = "Remove document info metadata from the PDF",
+            defaultValue = "false",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Boolean removeMetadata;
 
-    @Schema(description = "Remove links from the PDF", defaultValue = "false")
-    private boolean removeLinks;
+    @Schema(
+            description = "Remove links from the PDF",
+            defaultValue = "false",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Boolean removeLinks;
 
-    @Schema(description = "Remove fonts from the PDF", defaultValue = "false")
-    private boolean removeFonts;
+    @Schema(
+            description = "Remove fonts from the PDF",
+            defaultValue = "false",
+            requiredMode = Schema.RequiredMode.REQUIRED)
+    private Boolean removeFonts;
 }

src/main/java/stirling/software/SPDF/model/api/security/SignPDFWithCertRequest.java

@@ -15,7 +15,8 @@ public class SignPDFWithCertRequest extends PDFFile {
 
     @Schema(
             description = "The type of the digital certificate",
-            allowableValues = {"PEM", "PKCS12", "JKS"})
+            allowableValues = {"PEM", "PKCS12", "JKS"},
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private String certType;
 
     @Schema(
@@ -36,24 +37,31 @@ public class SignPDFWithCertRequest extends PDFFile {
     @Schema(description = "The password for the keystore or the private key", format = "password")
     private String password;
 
-    @Schema(description = "Whether to visually show the signature in the PDF file")
+    @Schema(
+            description = "Whether to visually show the signature in the PDF file",
+            defaultValue = "false",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private Boolean showSignature;
 
-    @Schema(description = "The reason for signing the PDF")
+    @Schema(description = "The reason for signing the PDF", defaultValue = "Signed by SPDF")
     private String reason;
 
-    @Schema(description = "The location where the PDF is signed")
+    @Schema(description = "The location where the PDF is signed", defaultValue = "SPDF")
     private String location;
 
-    @Schema(description = "The name of the signer")
+    @Schema(description = "The name of the signer", defaultValue = "SPDF")
     private String name;
 
     @Schema(
             description =
                     "The page number where the signature should be visible. This is required if"
-                            + " showSignature is set to true")
+                            + " showSignature is set to true",
+            defaultValue = "1")
     private Integer pageNumber;
 
-    @Schema(description = "Whether to visually show a signature logo along with the signature")
+    @Schema(
+            description = "Whether to visually show a signature logo along with the signature",
+            defaultValue = "true",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private Boolean showLogo;
 }

src/main/java/stirling/software/SPDF/model/api/security/SignatureValidationRequest.java

@@ -13,6 +13,8 @@ import stirling.software.SPDF.model.api.PDFFile;
 @EqualsAndHashCode(callSuper = true)
 public class SignatureValidationRequest extends PDFFile {
 
-    @Schema(description = "(Optional) file to compare PDF cert signatures against x.509 format")
+    @Schema(
+            description = "(Optional) file to compare PDF cert signatures against x.509 format",
+            requiredMode = Schema.RequiredMode.NOT_REQUIRED)
     private MultipartFile certFile;
 }

src/main/java/stirling/software/SPDF/model/api/user/UpdateUserDetails.java

@@ -9,6 +9,9 @@ import lombok.EqualsAndHashCode;
 @EqualsAndHashCode(callSuper = true)
 public class UpdateUserDetails extends UpdateUserUsername {
 
-    @Schema(description = "new password for user")
+    @Schema(
+            description = "new password for user",
+            format = "password",
+            requiredMode = Schema.RequiredMode.REQUIRED)
     private String newPassword;
 }

src/main/java/stirling/software/SPDF/model/api/user/UpdateUserUsername.java

@@ -9,6 +9,6 @@ import lombok.EqualsAndHashCode;
 @EqualsAndHashCode(callSuper = true)
 public class UpdateUserUsername extends UsernameAndPass {
 
-    @Schema(description = "new password for user")
+    @Schema(description = "new username for user")
     private String newUsername;
 }

src/main/java/stirling/software/SPDF/model/api/user/Username.java

@@ -9,6 +9,6 @@ import lombok.EqualsAndHashCode;
 @EqualsAndHashCode
 public class Username {
 
-    @Schema(description = "username of user")
+    @Schema(description = "username of user", requiredMode = Schema.RequiredMode.REQUIRED)
     private String username;
 }

src/main/java/stirling/software/SPDF/model/api/user/UsernameAndPass.java

@@ -9,6 +9,6 @@ import lombok.EqualsAndHashCode;
 @EqualsAndHashCode(callSuper = true)
 public class UsernameAndPass extends Username {
 
-    @Schema(description = "password of user")
+    @Schema(description = "password of user", format = "password")
     private String password;
 }