diff --git a/app/core/src/main/java/stirling/software/SPDF/config/swagger/CsvConversionResponse.java b/app/core/src/main/java/stirling/software/SPDF/config/swagger/CsvConversionResponse.java new file mode 100644 index 000000000..b42983881 --- /dev/null +++ b/app/core/src/main/java/stirling/software/SPDF/config/swagger/CsvConversionResponse.java @@ -0,0 +1,64 @@ +package stirling.software.SPDF.config.swagger; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; + +/** + * API response annotation for PDF to CSV conversions. Use for endpoints that convert PDF tables to + * CSV format. + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +@ApiResponses( + value = { + @ApiResponse( + responseCode = "200", + description = "PDF tables extracted successfully to CSV format", + content = + @Content( + mediaType = "text/csv", + schema = + @Schema( + type = "string", + format = "binary", + description = + "CSV file containing extracted table data"))), + @ApiResponse( + responseCode = "400", + description = + "Bad request - Invalid input parameters, unsupported format, or corrupted PDF", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "413", + description = "Payload too large - File exceeds maximum allowed size", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "422", + description = + "Unprocessable entity - PDF is valid but contains no extractable table data", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "500", + description = "Internal server error - Unexpected error during CSV extraction", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))) + }) +public @interface CsvConversionResponse {} diff --git a/app/core/src/main/java/stirling/software/SPDF/config/swagger/HtmlConversionResponse.java b/app/core/src/main/java/stirling/software/SPDF/config/swagger/HtmlConversionResponse.java new file mode 100644 index 000000000..85de0fcf7 --- /dev/null +++ b/app/core/src/main/java/stirling/software/SPDF/config/swagger/HtmlConversionResponse.java @@ -0,0 +1,63 @@ +package stirling.software.SPDF.config.swagger; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; + +/** + * API response annotation for PDF to HTML conversions. Use for endpoints that convert PDF to HTML + * format. + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +@ApiResponses( + value = { + @ApiResponse( + responseCode = "200", + description = "PDF converted successfully to HTML format", + content = + @Content( + mediaType = "text/html", + schema = + @Schema( + type = "string", + format = "binary", + description = "HTML file converted from PDF"))), + @ApiResponse( + responseCode = "400", + description = + "Bad request - Invalid input parameters, unsupported format, or corrupted PDF", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "413", + description = "Payload too large - File exceeds maximum allowed size", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "422", + description = + "Unprocessable entity - PDF is valid but cannot be converted to HTML format", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "500", + description = "Internal server error - Unexpected error during HTML conversion", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))) + }) +public @interface HtmlConversionResponse {} diff --git a/app/core/src/main/java/stirling/software/SPDF/config/swagger/JavaScriptResponse.java b/app/core/src/main/java/stirling/software/SPDF/config/swagger/JavaScriptResponse.java new file mode 100644 index 000000000..f78c92b68 --- /dev/null +++ b/app/core/src/main/java/stirling/software/SPDF/config/swagger/JavaScriptResponse.java @@ -0,0 +1,65 @@ +package stirling.software.SPDF.config.swagger; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; + +/** + * API response annotation for JavaScript extraction from PDFs. Use for endpoints that extract + * JavaScript code from PDF documents. + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +@ApiResponses( + value = { + @ApiResponse( + responseCode = "200", + description = "JavaScript extracted successfully from PDF", + content = + @Content( + mediaType = "text/plain", + schema = + @Schema( + type = "string", + format = "binary", + description = + "JavaScript code extracted from PDF"))), + @ApiResponse( + responseCode = "400", + description = + "Bad request - Invalid input parameters, unsupported format, or corrupted PDF", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "413", + description = "Payload too large - File exceeds maximum allowed size", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "422", + description = + "Unprocessable entity - PDF is valid but contains no JavaScript code", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "500", + description = + "Internal server error - Unexpected error during JavaScript extraction", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))) + }) +public @interface JavaScriptResponse {} diff --git a/app/core/src/main/java/stirling/software/SPDF/config/swagger/MarkdownConversionResponse.java b/app/core/src/main/java/stirling/software/SPDF/config/swagger/MarkdownConversionResponse.java new file mode 100644 index 000000000..a6f972183 --- /dev/null +++ b/app/core/src/main/java/stirling/software/SPDF/config/swagger/MarkdownConversionResponse.java @@ -0,0 +1,65 @@ +package stirling.software.SPDF.config.swagger; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; + +/** + * API response annotation for PDF to Markdown conversions. Use for endpoints that convert PDF to + * Markdown format. + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +@ApiResponses( + value = { + @ApiResponse( + responseCode = "200", + description = "PDF converted successfully to Markdown format", + content = + @Content( + mediaType = "text/markdown", + schema = + @Schema( + type = "string", + format = "binary", + description = + "Markdown file converted from PDF"))), + @ApiResponse( + responseCode = "400", + description = + "Bad request - Invalid input parameters, unsupported format, or corrupted PDF", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "413", + description = "Payload too large - File exceeds maximum allowed size", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "422", + description = + "Unprocessable entity - PDF is valid but cannot be converted to Markdown format", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "500", + description = + "Internal server error - Unexpected error during Markdown conversion", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))) + }) +public @interface MarkdownConversionResponse {} diff --git a/app/core/src/main/java/stirling/software/SPDF/config/swagger/XmlConversionResponse.java b/app/core/src/main/java/stirling/software/SPDF/config/swagger/XmlConversionResponse.java new file mode 100644 index 000000000..942c879bb --- /dev/null +++ b/app/core/src/main/java/stirling/software/SPDF/config/swagger/XmlConversionResponse.java @@ -0,0 +1,63 @@ +package stirling.software.SPDF.config.swagger; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; + +/** + * API response annotation for PDF to XML conversions. Use for endpoints that convert PDF to XML + * format. + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +@ApiResponses( + value = { + @ApiResponse( + responseCode = "200", + description = "PDF converted successfully to XML format", + content = + @Content( + mediaType = "application/xml", + schema = + @Schema( + type = "string", + format = "binary", + description = "XML file converted from PDF"))), + @ApiResponse( + responseCode = "400", + description = + "Bad request - Invalid input parameters, unsupported format, or corrupted PDF", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "413", + description = "Payload too large - File exceeds maximum allowed size", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "422", + description = + "Unprocessable entity - PDF is valid but cannot be converted to XML format", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))), + @ApiResponse( + responseCode = "500", + description = "Internal server error - Unexpected error during XML conversion", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ErrorResponse.class))) + }) +public @interface XmlConversionResponse {} diff --git a/app/core/src/main/java/stirling/software/SPDF/controller/api/ToSinglePageController.java b/app/core/src/main/java/stirling/software/SPDF/controller/api/ToSinglePageController.java index 1b5f1a750..7401666f7 100644 --- a/app/core/src/main/java/stirling/software/SPDF/controller/api/ToSinglePageController.java +++ b/app/core/src/main/java/stirling/software/SPDF/controller/api/ToSinglePageController.java @@ -20,6 +20,7 @@ import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; +import stirling.software.SPDF.config.swagger.StandardPdfResponse; import stirling.software.common.annotations.AutoJobPostMapping; import stirling.software.common.model.api.PDFFile; import stirling.software.common.service.CustomPDFDocumentFactory; @@ -34,6 +35,7 @@ public class ToSinglePageController { private final CustomPDFDocumentFactory pdfDocumentFactory; @AutoJobPostMapping(consumes = "multipart/form-data", value = "/pdf-to-single-page") + @StandardPdfResponse @Operation( summary = "Convert a multi-page PDF into a single long page PDF", description = diff --git a/app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ExtractCSVController.java b/app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ExtractCSVController.java index 1ce2e6fc3..cc500369e 100644 --- a/app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ExtractCSVController.java +++ b/app/core/src/main/java/stirling/software/SPDF/controller/api/converters/ExtractCSVController.java @@ -27,6 +27,7 @@ import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; +import stirling.software.SPDF.config.swagger.CsvConversionResponse; import stirling.software.SPDF.model.api.PDFWithPageNums; import stirling.software.SPDF.pdf.FlexibleCSVWriter; import stirling.software.common.annotations.AutoJobPostMapping; @@ -47,6 +48,7 @@ public class ExtractCSVController { private final CustomPDFDocumentFactory pdfDocumentFactory; @AutoJobPostMapping(value = "/pdf/csv", consumes = "multipart/form-data") + @CsvConversionResponse @Operation( summary = "Extracts a CSV document from a PDF", description = diff --git a/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/ExtractImageScansController.java b/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/ExtractImageScansController.java index d40a6a292..93dfe11eb 100644 --- a/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/ExtractImageScansController.java +++ b/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/ExtractImageScansController.java @@ -29,6 +29,7 @@ import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; +import stirling.software.SPDF.config.swagger.MultiFileResponse; import stirling.software.SPDF.model.api.misc.ExtractImageScansRequest; import stirling.software.common.annotations.AutoJobPostMapping; import stirling.software.common.service.CustomPDFDocumentFactory; @@ -51,6 +52,7 @@ public class ExtractImageScansController { private final CustomPDFDocumentFactory pdfDocumentFactory; @AutoJobPostMapping(consumes = "multipart/form-data", value = "/extract-image-scans") + @MultiFileResponse @Operation( summary = "Extract image scans from an input file", description = diff --git a/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/PageNumbersController.java b/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/PageNumbersController.java index 864735880..3d6e923f0 100644 --- a/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/PageNumbersController.java +++ b/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/PageNumbersController.java @@ -23,6 +23,7 @@ import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; +import stirling.software.SPDF.config.swagger.StandardPdfResponse; import stirling.software.SPDF.model.api.misc.AddPageNumbersRequest; import stirling.software.common.annotations.AutoJobPostMapping; import stirling.software.common.service.CustomPDFDocumentFactory; @@ -38,6 +39,7 @@ public class PageNumbersController { private final CustomPDFDocumentFactory pdfDocumentFactory; @AutoJobPostMapping(value = "/add-page-numbers", consumes = "multipart/form-data") + @StandardPdfResponse @Operation( summary = "Add page numbers to a PDF document", description = diff --git a/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/ShowJavascript.java b/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/ShowJavascript.java index 56f43ca41..fc5a2cd18 100644 --- a/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/ShowJavascript.java +++ b/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/ShowJavascript.java @@ -19,6 +19,7 @@ import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; +import stirling.software.SPDF.config.swagger.JavaScriptResponse; import stirling.software.common.annotations.AutoJobPostMapping; import stirling.software.common.model.api.PDFFile; import stirling.software.common.service.CustomPDFDocumentFactory; @@ -33,6 +34,7 @@ public class ShowJavascript { private final CustomPDFDocumentFactory pdfDocumentFactory; @AutoJobPostMapping(consumes = "multipart/form-data", value = "/show-javascript") + @JavaScriptResponse @Operation( summary = "Grabs all JS from a PDF and returns a single JS file with all code", description = "desc. Input:PDF Output:JS Type:SISO") diff --git a/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/StampController.java b/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/StampController.java index 590ace5d4..a52626832 100644 --- a/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/StampController.java +++ b/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/StampController.java @@ -36,6 +36,7 @@ import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; +import stirling.software.SPDF.config.swagger.StandardPdfResponse; import stirling.software.SPDF.model.api.misc.AddStampRequest; import stirling.software.common.annotations.AutoJobPostMapping; import stirling.software.common.service.CustomPDFDocumentFactory; @@ -53,6 +54,7 @@ public class StampController { private final TempFileManager tempFileManager; @AutoJobPostMapping(consumes = "multipart/form-data", value = "/add-stamp") + @StandardPdfResponse @Operation( summary = "Add stamp to a PDF file", description = diff --git a/app/core/src/main/java/stirling/software/SPDF/model/api/converters/ConvertPDFToMarkdown.java b/app/core/src/main/java/stirling/software/SPDF/model/api/converters/ConvertPDFToMarkdown.java index e9b326a2a..5febf16d0 100644 --- a/app/core/src/main/java/stirling/software/SPDF/model/api/converters/ConvertPDFToMarkdown.java +++ b/app/core/src/main/java/stirling/software/SPDF/model/api/converters/ConvertPDFToMarkdown.java @@ -9,6 +9,7 @@ import org.springframework.web.multipart.MultipartFile; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.tags.Tag; +import stirling.software.SPDF.config.swagger.MarkdownConversionResponse; import stirling.software.common.annotations.AutoJobPostMapping; import stirling.software.common.model.api.PDFFile; import stirling.software.common.util.PDFToFile; @@ -19,6 +20,7 @@ import stirling.software.common.util.PDFToFile; public class ConvertPDFToMarkdown { @AutoJobPostMapping(consumes = "multipart/form-data", value = "/pdf/markdown") + @MarkdownConversionResponse @Operation( summary = "Convert PDF to Markdown", description =