From f2521717ae634fe45ebc682792de4b0859fefb94 Mon Sep 17 00:00:00 2001
From: Anthony Stirling <77850077+Frooodle@users.noreply.github.com>
Date: Mon, 8 May 2023 15:20:04 +0100
Subject: [PATCH] more docs

---
 .../api/RearrangePagesPDFController.java      | 24 ++++++++++++++++---
 .../controller/api/SplitPDFController.java    | 13 +++++++++-
 2 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/src/main/java/stirling/software/SPDF/controller/api/RearrangePagesPDFController.java b/src/main/java/stirling/software/SPDF/controller/api/RearrangePagesPDFController.java
index 4ed72e92..9fdf2d0b 100644
--- a/src/main/java/stirling/software/SPDF/controller/api/RearrangePagesPDFController.java
+++ b/src/main/java/stirling/software/SPDF/controller/api/RearrangePagesPDFController.java
@@ -15,6 +15,8 @@ import org.springframework.web.bind.annotation.RequestPart;
 import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import stirling.software.SPDF.utils.PdfUtils;
 
 @RestController
@@ -22,9 +24,17 @@ public class RearrangePagesPDFController {
 
     private static final Logger logger = LoggerFactory.getLogger(RearrangePagesPDFController.class);
 
+
     @PostMapping(consumes = "multipart/form-data", value = "/remove-pages")
-    public ResponseEntity<byte[]> deletePages(@RequestPart(required = true, value = "fileInput") MultipartFile pdfFile, @RequestParam("pagesToDelete") String pagesToDelete)
-            throws IOException {
+    @Operation(summary = "Remove pages from a PDF file",
+            description = "This endpoint removes specified pages from a given PDF file. Users can provide a comma-separated list of page numbers or ranges to delete.")
+    public ResponseEntity<byte[]> deletePages(
+            @RequestPart(required = true, value = "fileInput")
+            @Parameter(description = "The input PDF file from which pages will be removed")
+                    MultipartFile pdfFile,
+            @RequestParam("pagesToDelete")
+            @Parameter(description = "Comma-separated list of pages or page ranges to delete, e.g., '1,3,5-8'")
+                    String pagesToDelete) throws IOException {
 
         PDDocument document = PDDocument.load(pdfFile.getBytes());
 
@@ -70,7 +80,15 @@ public class RearrangePagesPDFController {
     }
 
     @PostMapping(consumes = "multipart/form-data", value = "/rearrange-pages")
-    public ResponseEntity<byte[]> rearrangePages(@RequestPart(required = true, value = "fileInput") MultipartFile pdfFile, @RequestParam("pageOrder") String pageOrder) {
+    @Operation(summary = "Rearrange pages in a PDF file",
+            description = "This endpoint rearranges pages in a given PDF file based on the specified page order. Users can provide a page order as a comma-separated list of page numbers or page ranges.")
+    public ResponseEntity<byte[]> rearrangePages(
+            @RequestPart(required = true, value = "fileInput")
+            @Parameter(description = "The input PDF file to rearrange pages")
+                    MultipartFile pdfFile,
+            @RequestParam("pageOrder")
+            @Parameter(description = "The new page order as a comma-separated list of page numbers or page ranges (e.g., '1,3,5-7')")
+                    String pageOrder) {
         try {
             // Load the input PDF
             PDDocument document = PDDocument.load(pdfFile.getInputStream());
diff --git a/src/main/java/stirling/software/SPDF/controller/api/SplitPDFController.java b/src/main/java/stirling/software/SPDF/controller/api/SplitPDFController.java
index f6deb80c..99152e69 100644
--- a/src/main/java/stirling/software/SPDF/controller/api/SplitPDFController.java
+++ b/src/main/java/stirling/software/SPDF/controller/api/SplitPDFController.java
@@ -27,13 +27,24 @@ import org.springframework.web.bind.annotation.RequestPart;
 import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+
 @RestController
 public class SplitPDFController {
 
     private static final Logger logger = LoggerFactory.getLogger(SplitPDFController.class);
 
     @PostMapping(consumes = "multipart/form-data", value = "/split-pages")
-    public ResponseEntity<Resource> splitPdf(@RequestPart(required = true, value = "fileInput") MultipartFile file, @RequestParam("pages") String pages) throws IOException {
+    @Operation(summary = "Split a PDF file into separate documents",
+            description = "This endpoint splits a given PDF file into separate documents based on the specified page numbers or ranges. Users can specify pages using individual numbers, ranges, or 'all' for every page.")
+    public ResponseEntity<Resource> splitPdf(
+            @RequestPart(required = true, value = "fileInput")
+            @Parameter(description = "The input PDF file to be split")
+                    MultipartFile file,
+            @RequestParam("pages")
+            @Parameter(description = "The pages to be included in separate documents. Specify individual page numbers (e.g., '1,3,5'), ranges (e.g., '1-3,5-7'), or 'all' for every page.")
+                    String pages) throws IOException {
         // parse user input
 
         // open the pdf document