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`.
veraPDF · Feb 12, 2024 · 0c84748 · 0c84748
1 parent 35e4b68
commit 0c84748
Show file tree

Hide file tree

Showing 2 changed files with 33 additions and 44 deletions.
diff --git 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
@@ -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 <a href="mailto:[email protected]">Carl Wilson</a>
  */
 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) {