From 0c84748e4a3f145defd11ac1966b9731cffd3450 Mon Sep 17 00:00:00 2001 From: Carl Wilson Date: Thu, 8 Feb 2024 12:29:49 +0000 Subject: [PATCH] DOCS: Better Swagger docs for validate methods - consolidated URL validation methods; - improved documentation of methods and params; - factored string duplication to constants for some cases; and - added quotes to param in `Dockerfile`. --- Dockerfile | 2 +- .../rest/resources/ValidateResource.java | 75 ++++++++----------- 2 files changed, 33 insertions(+), 44 deletions(-) diff --git a/Dockerfile b/Dockerfile index ef773af3..5d9ff5d2 100644 --- a/Dockerfile +++ b/Dockerfile @@ -65,4 +65,4 @@ COPY --from=app-builder /build/veraPDF-rest/config /opt/verapdf-rest/config/ VOLUME /var/opt/verapdf-rest EXPOSE 8080 -ENTRYPOINT dumb-init java $JAVA_OPTS -Djava.awt.headless=true -jar /opt/verapdf-rest/verapdf-rest-${VERAPDF_REST_VERSION}.jar server /var/opt/verapdf-rest/config/server.yml +ENTRYPOINT dumb-init java "$JAVA_OPTS" -Djava.awt.headless=true -jar /opt/verapdf-rest/verapdf-rest-${VERAPDF_REST_VERSION}.jar server /var/opt/verapdf-rest/config/server.yml diff --git a/src/main/java/org/verapdf/rest/resources/ValidateResource.java b/src/main/java/org/verapdf/rest/resources/ValidateResource.java index 27062eb1..95037885 100644 --- a/src/main/java/org/verapdf/rest/resources/ValidateResource.java +++ b/src/main/java/org/verapdf/rest/resources/ValidateResource.java @@ -13,10 +13,10 @@ import java.security.DigestInputStream; import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; -import java.text.Format; import javax.ws.rs.BadRequestException; import javax.ws.rs.Consumes; +import javax.ws.rs.DefaultValue; import javax.ws.rs.GET; import javax.ws.rs.HeaderParam; import javax.ws.rs.InternalServerErrorException; @@ -37,6 +37,7 @@ import org.verapdf.io.SeekableInputStream; import org.verapdf.pdfa.Foundries; import org.verapdf.pdfa.flavours.PDFAFlavour; +import org.verapdf.pdfa.results.ValidationResult; import org.verapdf.pdfa.validation.validators.ValidatorConfig; import org.verapdf.processor.BatchProcessor; import org.verapdf.processor.FormatOption; @@ -60,6 +61,11 @@ * @author Carl Wilson */ public class ValidateResource { + private static final String PARAM_PROFILE_DESC = "the String id of the PDF Specification to validate against. " + + "must be one of: (auto, 1b, 1a, 2b, 2a, 2u, 3b, 3a, 3u, 4, 4e, 4f, ua1 or ua2). " + + "Selecting 'auto' allows the validator to detect and apply the appropriate specification from the PDF metadata."; + private static final String PARAM_FILE_SIZE_DESC = "the size of the PDF to be validated in bytes, read from the request header."; + private static final String VALIDATION_OP_DESC = "against the selected PDF Specification/Validaton profile and return a report comprising the valdiation results."; // java.security.digest name for the SHA-1 algorithm private static final String SHA1_NAME = "SHA-1"; //$NON-NLS-1$ private static final String FILE_SIZE_HEADER = "X-File-Size"; @@ -104,65 +110,48 @@ public static ComponentDetails getDetails() { */ @POST @Path("/{profileId}") - @Operation(summary = "Validate the uploaded stream against the selected profile and return validation result") + @Operation(summary = "Validate the uploaded file " + VALIDATION_OP_DESC) @ApiResponses(value = { @ApiResponse(responseCode = "200", description = "OK", content = { - @Content(mediaType = "application/xml", schema = @Schema(implementation = InputStream.class)), - @Content(mediaType = "application/json", schema = @Schema(implementation = InputStream.class)), - @Content(mediaType = "text/html", schema = @Schema(implementation = InputStream.class)) }) }) + @Content(mediaType = "application/xml", schema = @Schema(implementation = BatchSummary.class)), + @Content(mediaType = "application/json", schema = @Schema(implementation = BatchSummary.class)), + @Content(mediaType = "text/html", schema = @Schema(implementation = BatchSummary.class)) }) }) @Consumes(MediaType.MULTIPART_FORM_DATA) @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON, MediaType.TEXT_HTML }) - public static Response validateXml(@Parameter(description = "the String id of the Validation profile " + - "(auto, 1b, 1a, 2b, 2a, 2u, 3b, 3a, 3u, 4, 4e, 4f, ua1 or ua2)") @PathParam("profileId") String profileId, + public static Response validateXml( + @Parameter(description = PARAM_PROFILE_DESC) @PathParam("profileId") String profileId, @Parameter(description = "the hex String representation of the file's SHA-1 hash", required = false, allowEmptyValue = true) @FormDataParam("sha1Hex") String sha1Hex, - @Parameter(name = "file", schema = @Schema(implementation = File.class), style = ParameterStyle.FORM, description = "an InputStream of the PDF to be validated") @FormDataParam("file") InputStream uploadedInputStream, + @Parameter(name = "file", schema = @Schema(implementation = File.class), style = ParameterStyle.FORM, description = "a PDF file uploaded to be validated") @FormDataParam("file") InputStream uploadedInputStream, @Parameter(hidden = true) @FormDataParam("file") final FormDataContentDisposition contentDispositionHeader, - @Parameter(name = FILE_SIZE_HEADER, description = "a size of the PDF to be validated") @HeaderParam(FILE_SIZE_HEADER) Integer fileSize, + @Parameter(name = FILE_SIZE_HEADER, description = PARAM_FILE_SIZE_DESC) @HeaderParam(FILE_SIZE_HEADER) Integer fileSize, @HeaderParam("Accept") String accepts) { - FormatOption formatOption = formatOptionFromAccepts(accepts); return Response - .ok(validateFile(uploadedInputStream, contentDispositionHeader, profileId, sha1Hex, formatOption, + .ok(validateFile(uploadedInputStream, contentDispositionHeader, profileId, sha1Hex, + formatOptionFromAccepts(accepts), fileSize), accepts) .build(); } @POST @Path("/url/{profileId}") - @Operation(summary = "Validate PDF given by URL against the selected profile and return validation result") + @Operation(summary = "Validate PDF located at the supplied URL " + VALIDATION_OP_DESC) @ApiResponses(value = { @ApiResponse(responseCode = "200", description = "OK", content = { - @Content(mediaType = "application/xml", schema = @Schema(implementation = InputStream.class)), - @Content(mediaType = "application/json", schema = @Schema(implementation = InputStream.class)), - @Content(mediaType = "text/html", schema = @Schema(implementation = InputStream.class)) }) }) + @Content(mediaType = "application/xml", schema = @Schema(implementation = BatchSummary.class)), + @Content(mediaType = "application/json", schema = @Schema(implementation = BatchSummary.class)), + @Content(mediaType = "text/html", schema = @Schema(implementation = BatchSummary.class)) }) }) @Consumes(MediaType.MULTIPART_FORM_DATA) - @Produces({ MediaType.APPLICATION_XML }) - public static InputStream validateXml(@Parameter(description = "the String id of the Validation profile " + - "(auto, 1b, 1a, 2b, 2a, 2u, 3b, 3a, 3u, 4, 4e, 4f, ua1 or ua2)") @PathParam("profileId") String profileId, - @Parameter(description = "a URL of PDF to be validated") @FormDataParam("url") String urlLink, - @Parameter(name = FILE_SIZE_HEADER, description = "a size of the PDF to be validated") @HeaderParam(FILE_SIZE_HEADER) Integer fileSize) { - return validateUrl(urlLink, profileId, FormatOption.XML, fileSize); - } - - @POST - @Path("/url/{profileId}") - @Consumes(MediaType.MULTIPART_FORM_DATA) - @Produces({ MediaType.APPLICATION_JSON }) - public static InputStream validateJson(@Parameter(description = "the String id of the Validation profile " + - "(auto, 1b, 1a, 2b, 2a, 2u, 3b, 3a, 3u, 4, 4e, 4f, ua1 or ua2)") @PathParam("profileId") String profileId, - @Parameter(description = "a URL of PDF to be validated") @FormDataParam("url") String urlLink, - @Parameter(name = FILE_SIZE_HEADER, description = "a size of the PDF to be validated") @HeaderParam(FILE_SIZE_HEADER) Integer fileSize) { - return validateUrl(urlLink, profileId, FormatOption.JSON, fileSize); - } - - @POST - @Path("/url/{profileId}") - @Consumes(MediaType.MULTIPART_FORM_DATA) - @Produces({ MediaType.TEXT_HTML }) - public static InputStream validateHtml(@Parameter(description = "the String id of the Validation profile " + - "(auto, 1b, 1a, 2b, 2a, 2u, 3b, 3a, 3u, 4, 4e, 4f, ua1 or ua2)") @PathParam("profileId") String profileId, - @Parameter(description = "a URL of PDF to be validated") @FormDataParam("url") String urlLink, - @Parameter(name = FILE_SIZE_HEADER, description = "a size of the PDF to be validated") @HeaderParam(FILE_SIZE_HEADER) Integer fileSize) { - return validateUrl(urlLink, profileId, FormatOption.HTML, fileSize); + @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON, MediaType.TEXT_HTML }) + public static Response validateXml( + @Parameter(description = PARAM_PROFILE_DESC) @PathParam("profileId") String profileId, + @Parameter(description = "a URL that resolves to PDF resource to be validated") @FormDataParam("url") String urlLink, + @Parameter(name = FILE_SIZE_HEADER, description = PARAM_FILE_SIZE_DESC) @HeaderParam(FILE_SIZE_HEADER) Integer fileSize, + @HeaderParam("Accept") String accepts) { + return Response + .ok(validateUrl(urlLink, profileId, + formatOptionFromAccepts(accepts), + fileSize), accepts) + .build(); } public static void setMaxFileSize(Integer maxFileSize) {