From 0f935b92cb5a1f98079ecd68a4692e7594c89c16 Mon Sep 17 00:00:00 2001 From: Anthony Stirling <77850077+Frooodle@users.noreply.github.com> Date: Mon, 8 May 2023 15:07:53 +0100 Subject: [PATCH] api docs --- .../converters/ConvertImgPDFController.java | 39 ++++++++++++--- .../api/converters/ConvertPDFToOffice.java | 37 ++++++++++++--- .../other/ExtractImageScansController.java | 27 +++++++++-- .../api/other/ExtractImagesController.java | 14 +++++- .../api/other/MetadataController.java | 47 ++++++++++++++++--- .../controller/api/other/OCRController.java | 40 +++++++++++++--- .../api/security/WatermarkController.java | 30 ++++++++++-- 7 files changed, 197 insertions(+), 37 deletions(-) diff --git a/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertImgPDFController.java b/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertImgPDFController.java index 12172127..3c57d59a 100644 --- a/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertImgPDFController.java +++ b/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertImgPDFController.java @@ -17,16 +17,34 @@ 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; - +import io.swagger.v3.oas.annotations.media.Schema; @RestController public class ConvertImgPDFController { private static final Logger logger = LoggerFactory.getLogger(ConvertImgPDFController.class); @PostMapping(consumes = "multipart/form-data", value = "/pdf-to-img") - public ResponseEntity convertToImage(@RequestPart(required = true, value = "fileInput") MultipartFile file, @RequestParam("imageFormat") String imageFormat, - @RequestParam("singleOrMultiple") String singleOrMultiple, @RequestParam("colorType") String colorType, @RequestParam("dpi") String dpi) throws IOException { + @Operation(summary = "Convert PDF to image(s)", + description = "This endpoint converts a PDF file to image(s) with the specified image format, color type, and DPI. Users can choose to get a single image or multiple images.") + public ResponseEntity convertToImage( + @RequestPart(required = true, value = "fileInput") + @Parameter(description = "The input PDF file to be converted") + MultipartFile file, + @RequestParam("imageFormat") + @Parameter(description = "The output image format", schema = @Schema(allowableValues = {"png", "jpeg", "jpg", "gif"})) + String imageFormat, + @RequestParam("singleOrMultiple") + @Parameter(description = "Choose between a single image containing all pages or separate images for each page", schema = @Schema(allowableValues = {"single", "multiple"})) + String singleOrMultiple, + @RequestParam("colorType") + @Parameter(description = "The color type of the output image(s)", schema = @Schema(allowableValues = {"rgb", "greyscale", "blackwhite"})) + String colorType, + @RequestParam("dpi") + @Parameter(description = "The DPI (dots per inch) for the output image(s)") + String dpi) throws IOException { byte[] pdfBytes = file.getBytes(); ImageType colorTypeResult = ImageType.RGB; @@ -62,9 +80,18 @@ public class ConvertImgPDFController { } @PostMapping(consumes = "multipart/form-data", value = "/img-to-pdf") - public ResponseEntity convertToPdf(@RequestPart(required = true, value = "fileInput") MultipartFile[] file, - @RequestParam(defaultValue = "false", name = "stretchToFit") boolean stretchToFit, @RequestParam(defaultValue = "true", name = "autoRotate") boolean autoRotate) - throws IOException { + @Operation(summary = "Convert images to a PDF file", + description = "This endpoint converts one or more images to a PDF file. Users can specify whether to stretch the images to fit the PDF page, and whether to automatically rotate the images.") + public ResponseEntity convertToPdf( + @RequestPart(required = true, value = "fileInput") + @Parameter(description = "The input images to be converted to a PDF file") + MultipartFile[] file, + @RequestParam(defaultValue = "false", name = "stretchToFit") + @Parameter(description = "Whether to stretch the images to fit the PDF page or maintain the aspect ratio", example = "false") + boolean stretchToFit, + @RequestParam(defaultValue = "true", name = "autoRotate") + @Parameter(description = "Whether to automatically rotate the images to better fit the PDF page", example = "true") + boolean autoRotate) throws IOException { // Convert the file to PDF and get the resulting bytes System.out.println(stretchToFit); byte[] bytes = PdfUtils.imageToPdf(file, stretchToFit, autoRotate); diff --git a/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertPDFToOffice.java b/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertPDFToOffice.java index 29d16495..485dcf74 100644 --- a/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertPDFToOffice.java +++ b/src/main/java/stirling/software/SPDF/controller/api/converters/ConvertPDFToOffice.java @@ -9,8 +9,10 @@ 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.PDFToFile; - +import io.swagger.v3.oas.annotations.media.Schema; @RestController public class ConvertPDFToOffice { @@ -23,22 +25,43 @@ public class ConvertPDFToOffice { } @PostMapping(consumes = "multipart/form-data", value = "/pdf-to-presentation") - public ResponseEntity processPdfToPresentation(@RequestPart(required = true, value = "fileInput") MultipartFile inputFile, - @RequestParam("outputFormat") String outputFormat) throws IOException, InterruptedException { + @Operation(summary = "Convert PDF to Presentation format", + description = "This endpoint converts a given PDF file to a Presentation format.") + public ResponseEntity processPdfToPresentation( + @RequestPart(required = true, value = "fileInput") + @Parameter(description = "The input PDF file") + MultipartFile inputFile, + @RequestParam("outputFormat") + @Parameter(description = "The output Presentation format", schema = @Schema(allowableValues = {"ppt", "pptx", "odp"})) + String outputFormat) throws IOException, InterruptedException { PDFToFile pdfToFile = new PDFToFile(); return pdfToFile.processPdfToOfficeFormat(inputFile, outputFormat, "impress_pdf_import"); } @PostMapping(consumes = "multipart/form-data", value = "/pdf-to-text") - public ResponseEntity processPdfToRTForTXT(@RequestPart(required = true, value = "fileInput") MultipartFile inputFile, - @RequestParam("outputFormat") String outputFormat) throws IOException, InterruptedException { + @Operation(summary = "Convert PDF to Text or RTF format", + description = "This endpoint converts a given PDF file to Text or RTF format.") + public ResponseEntity processPdfToRTForTXT( + @RequestPart(required = true, value = "fileInput") + @Parameter(description = "The input PDF file") + MultipartFile inputFile, + @RequestParam("outputFormat") + @Parameter(description = "The output Text or RTF format", schema = @Schema(allowableValues = {"rtf", "txt:Text"})) + String outputFormat) throws IOException, InterruptedException { PDFToFile pdfToFile = new PDFToFile(); return pdfToFile.processPdfToOfficeFormat(inputFile, outputFormat, "writer_pdf_import"); } @PostMapping(consumes = "multipart/form-data", value = "/pdf-to-word") - public ResponseEntity processPdfToWord(@RequestPart(required = true, value = "fileInput") MultipartFile inputFile, @RequestParam("outputFormat") String outputFormat) - throws IOException, InterruptedException { + @Operation(summary = "Convert PDF to Word document", + description = "This endpoint converts a given PDF file to a Word document format.") + public ResponseEntity processPdfToWord( + @RequestPart(required = true, value = "fileInput") + @Parameter(description = "The input PDF file") + MultipartFile inputFile, + @RequestParam("outputFormat") + @Parameter(description = "The output Word document format", schema = @Schema(allowableValues = {"doc", "docx", "odt"})) + String outputFormat) throws IOException, InterruptedException { PDFToFile pdfToFile = new PDFToFile(); return pdfToFile.processPdfToOfficeFormat(inputFile, outputFormat, "writer_pdf_import"); } diff --git a/src/main/java/stirling/software/SPDF/controller/api/other/ExtractImageScansController.java b/src/main/java/stirling/software/SPDF/controller/api/other/ExtractImageScansController.java index bb15eee9..89ca7064 100644 --- a/src/main/java/stirling/software/SPDF/controller/api/other/ExtractImageScansController.java +++ b/src/main/java/stirling/software/SPDF/controller/api/other/ExtractImageScansController.java @@ -29,6 +29,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; import stirling.software.SPDF.utils.ProcessExecutor; @@ -38,10 +40,27 @@ public class ExtractImageScansController { private static final Logger logger = LoggerFactory.getLogger(ExtractImageScansController.class); @PostMapping(consumes = "multipart/form-data", value = "/extract-image-scans") - public ResponseEntity extractImageScans(@RequestPart(required = true, value = "fileInput") MultipartFile inputFile, - @RequestParam(name = "angle_threshold", defaultValue = "5") int angleThreshold, @RequestParam(name = "tolerance", defaultValue = "20") int tolerance, - @RequestParam(name = "min_area", defaultValue = "8000") int minArea, @RequestParam(name = "min_contour_area", defaultValue = "500") int minContourArea, - @RequestParam(name = "border_size", defaultValue = "1") int borderSize) throws IOException, InterruptedException { + @Operation(summary = "Extract image scans from an input file", + description = "This endpoint extracts image scans from a given file based on certain parameters. Users can specify angle threshold, tolerance, minimum area, minimum contour area, and border size.") + public ResponseEntity extractImageScans( + @RequestPart(required = true, value = "fileInput") + @Parameter(description = "The input file containing image scans") + MultipartFile inputFile, + @RequestParam(name = "angle_threshold", defaultValue = "5") + @Parameter(description = "The angle threshold for the image scan extraction", example = "5") + int angleThreshold, + @RequestParam(name = "tolerance", defaultValue = "20") + @Parameter(description = "The tolerance for the image scan extraction", example = "20") + int tolerance, + @RequestParam(name = "min_area", defaultValue = "8000") + @Parameter(description = "The minimum area for the image scan extraction", example = "8000") + int minArea, + @RequestParam(name = "min_contour_area", defaultValue = "500") + @Parameter(description = "The minimum contour area for the image scan extraction", example = "500") + int minContourArea, + @RequestParam(name = "border_size", defaultValue = "1") + @Parameter(description = "The border size for the image scan extraction", example = "1") + int borderSize) throws IOException, InterruptedException { String fileName = inputFile.getOriginalFilename(); String extension = fileName.substring(fileName.lastIndexOf(".") + 1); diff --git a/src/main/java/stirling/software/SPDF/controller/api/other/ExtractImagesController.java b/src/main/java/stirling/software/SPDF/controller/api/other/ExtractImagesController.java index d935bd39..8d0034ab 100644 --- a/src/main/java/stirling/software/SPDF/controller/api/other/ExtractImagesController.java +++ b/src/main/java/stirling/software/SPDF/controller/api/other/ExtractImagesController.java @@ -26,15 +26,25 @@ 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; - +import io.swagger.v3.oas.annotations.media.Schema; @RestController public class ExtractImagesController { private static final Logger logger = LoggerFactory.getLogger(ExtractImagesController.class); @PostMapping(consumes = "multipart/form-data", value = "/extract-images") - public ResponseEntity extractImages(@RequestPart(required = true, value = "fileInput") MultipartFile file, @RequestParam("format") String format) throws IOException { + @Operation(summary = "Extract images from a PDF file", + description = "This endpoint extracts images from a given PDF file and returns them in a zip file. Users can specify the output image format.") + public ResponseEntity extractImages( + @RequestPart(required = true, value = "fileInput") + @Parameter(description = "The input PDF file containing images") + MultipartFile file, + @RequestParam("format") + @Parameter(description = "The output image format e.g., 'png', 'jpeg', or 'gif'", schema = @Schema(allowableValues = {"png", "jpeg", "gif"})) + String format) throws IOException { System.out.println(System.currentTimeMillis() + "file=" + file.getName() + ", format=" + format); PDDocument document = PDDocument.load(file.getBytes()); diff --git a/src/main/java/stirling/software/SPDF/controller/api/other/MetadataController.java b/src/main/java/stirling/software/SPDF/controller/api/other/MetadataController.java index 42309c39..5840cd64 100644 --- a/src/main/java/stirling/software/SPDF/controller/api/other/MetadataController.java +++ b/src/main/java/stirling/software/SPDF/controller/api/other/MetadataController.java @@ -17,6 +17,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 @@ -35,13 +37,44 @@ public class MetadataController { } @PostMapping(consumes = "multipart/form-data", value = "/update-metadata") - public ResponseEntity metadata(@RequestPart(required = true, value = "fileInput") MultipartFile pdfFile, - @RequestParam(value = "deleteAll", required = false, defaultValue = "false") Boolean deleteAll, @RequestParam(value = "author", required = false) String author, - @RequestParam(value = "creationDate", required = false) String creationDate, @RequestParam(value = "creator", required = false) String creator, - @RequestParam(value = "keywords", required = false) String keywords, @RequestParam(value = "modificationDate", required = false) String modificationDate, - @RequestParam(value = "producer", required = false) String producer, @RequestParam(value = "subject", required = false) String subject, - @RequestParam(value = "title", required = false) String title, @RequestParam(value = "trapped", required = false) String trapped, - @RequestParam Map allRequestParams) throws IOException { + @Operation(summary = "Update metadata of a PDF file", + description = "This endpoint allows you to update the metadata of a given PDF file. You can add, modify, or delete standard and custom metadata fields.") + public ResponseEntity metadata( + @RequestPart(required = true, value = "fileInput") + @Parameter(description = "The input PDF file to update metadata") + MultipartFile pdfFile, + @RequestParam(value = "deleteAll", required = false, defaultValue = "false") + @Parameter(description = "Delete all metadata if set to true") + Boolean deleteAll, + @RequestParam(value = "author", required = false) + @Parameter(description = "The author of the document") + String author, + @RequestParam(value = "creationDate", required = false) + @Parameter(description = "The creation date of the document (format: yyyy/MM/dd HH:mm:ss)") + String creationDate, + @RequestParam(value = "creator", required = false) + @Parameter(description = "The creator of the document") + String creator, + @RequestParam(value = "keywords", required = false) + @Parameter(description = "The keywords for the document") + String keywords, + @RequestParam(value = "modificationDate", required = false) + @Parameter(description = "The modification date of the document (format: yyyy/MM/dd HH:mm:ss)") + String modificationDate, + @RequestParam(value = "producer", required = false) + @Parameter(description = "The producer of the document") + String producer, + @RequestParam(value = "subject", required = false) + @Parameter(description = "The subject of the document") + String subject, + @RequestParam(value = "title", required = false) + @Parameter(description = "The title of the document") + String title, + @RequestParam(value = "trapped", required = false) + @Parameter(description = "The trapped status of the document") + String trapped, + @RequestParam Map allRequestParams) + throws IOException { // Load the PDF file into a PDDocument PDDocument document = PDDocument.load(pdfFile.getBytes()); diff --git a/src/main/java/stirling/software/SPDF/controller/api/other/OCRController.java b/src/main/java/stirling/software/SPDF/controller/api/other/OCRController.java index 5c7f2553..f1769dce 100644 --- a/src/main/java/stirling/software/SPDF/controller/api/other/OCRController.java +++ b/src/main/java/stirling/software/SPDF/controller/api/other/OCRController.java @@ -24,6 +24,9 @@ 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 io.swagger.v3.oas.annotations.media.Schema; import stirling.software.SPDF.utils.PdfUtils; import stirling.software.SPDF.utils.ProcessExecutor; @@ -43,13 +46,36 @@ public class OCRController { } @PostMapping(consumes = "multipart/form-data", value = "/ocr-pdf") - public ResponseEntity processPdfWithOCR(@RequestPart(required = true, value = "fileInput") MultipartFile inputFile, - @RequestParam("languages") List selectedLanguages, @RequestParam(name = "sidecar", required = false) Boolean sidecar, - @RequestParam(name = "deskew", required = false) Boolean deskew, @RequestParam(name = "clean", required = false) Boolean clean, - @RequestParam(name = "clean-final", required = false) Boolean cleanFinal, @RequestParam(name = "ocrType", required = false) String ocrType, - @RequestParam(name = "ocrRenderType", required = false, defaultValue = "hocr") String ocrRenderType, - @RequestParam(name = "removeImagesAfter", required = false) Boolean removeImagesAfter) - throws IOException, InterruptedException { + @Operation(summary = "Process a PDF file with OCR", + description = "This endpoint processes a PDF file using OCR (Optical Character Recognition). Users can specify languages, sidecar, deskew, clean, cleanFinal, ocrType, ocrRenderType, and removeImagesAfter options.") + public ResponseEntity processPdfWithOCR( + @RequestPart(required = true, value = "fileInput") + @Parameter(description = "The input PDF file to be processed with OCR") + MultipartFile inputFile, + @RequestParam("languages") + @Parameter(description = "List of languages to use in OCR processing") + List selectedLanguages, + @RequestParam(name = "sidecar", required = false) + @Parameter(description = "Include OCR text in a sidecar text file if set to true") + Boolean sidecar, + @RequestParam(name = "deskew", required = false) + @Parameter(description = "Deskew the input file if set to true") + Boolean deskew, + @RequestParam(name = "clean", required = false) + @Parameter(description = "Clean the input file if set to true") + Boolean clean, + @RequestParam(name = "clean-final", required = false) + @Parameter(description = "Clean the final output if set to true") + Boolean cleanFinal, + @RequestParam(name = "ocrType", required = false) + @Parameter(description = "Specify the OCR type, e.g., 'skip-text', 'force-ocr', or 'Normal'", schema = @Schema(allowableValues = {"skip-text", "force-ocr", "Normal"})) + String ocrType, + @RequestParam(name = "ocrRenderType", required = false, defaultValue = "hocr") + @Parameter(description = "Specify the OCR render type, either 'hocr' or 'sandwich'", schema = @Schema(allowableValues = {"hocr", "sandwich"})) + String ocrRenderType, + @RequestParam(name = "removeImagesAfter", required = false) + @Parameter(description = "Remove images from the output PDF if set to true") + Boolean removeImagesAfter) throws IOException, InterruptedException { // --output-type pdfa if (selectedLanguages == null || selectedLanguages.isEmpty()) { diff --git a/src/main/java/stirling/software/SPDF/controller/api/security/WatermarkController.java b/src/main/java/stirling/software/SPDF/controller/api/security/WatermarkController.java index 8f9203b1..88955197 100644 --- a/src/main/java/stirling/software/SPDF/controller/api/security/WatermarkController.java +++ b/src/main/java/stirling/software/SPDF/controller/api/security/WatermarkController.java @@ -24,6 +24,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; import stirling.software.SPDF.utils.WatermarkRemover; @@ -31,10 +33,30 @@ import stirling.software.SPDF.utils.WatermarkRemover; public class WatermarkController { @PostMapping(consumes = "multipart/form-data", value = "/add-watermark") - public ResponseEntity addWatermark(@RequestPart(required = true, value = "fileInput") MultipartFile pdfFile, @RequestParam("watermarkText") String watermarkText, - @RequestParam(defaultValue = "30", name = "fontSize") float fontSize, @RequestParam(defaultValue = "0", name = "rotation") float rotation, - @RequestParam(defaultValue = "0.5", name = "opacity") float opacity, @RequestParam(defaultValue = "50", name = "widthSpacer") int widthSpacer, - @RequestParam(defaultValue = "50", name = "heightSpacer") int heightSpacer) throws IOException { + @Operation(summary = "Add watermark to a PDF file", + description = "This endpoint adds a watermark to a given PDF file. Users can specify the watermark text, font size, rotation, opacity, width spacer, and height spacer.") + public ResponseEntity addWatermark( + @RequestPart(required = true, value = "fileInput") + @Parameter(description = "The input PDF file to add a watermark") + MultipartFile pdfFile, + @RequestParam("watermarkText") + @Parameter(description = "The watermark text to add to the PDF file") + String watermarkText, + @RequestParam(defaultValue = "30", name = "fontSize") + @Parameter(description = "The font size of the watermark text", example = "30") + float fontSize, + @RequestParam(defaultValue = "0", name = "rotation") + @Parameter(description = "The rotation of the watermark text in degrees", example = "0") + float rotation, + @RequestParam(defaultValue = "0.5", name = "opacity") + @Parameter(description = "The opacity of the watermark text (0.0 - 1.0)", example = "0.5") + float opacity, + @RequestParam(defaultValue = "50", name = "widthSpacer") + @Parameter(description = "The width spacer between watermark texts", example = "50") + int widthSpacer, + @RequestParam(defaultValue = "50", name = "heightSpacer") + @Parameter(description = "The height spacer between watermark texts", example = "50") + int heightSpacer) throws IOException { // Load the input PDF PDDocument document = PDDocument.load(pdfFile.getInputStream());