Add endpoints and parameters description

veraPDF · Sep 28, 2023 · fa72885 · fa72885
1 parent 6375505
commit fa72885
Show file tree

Hide file tree

Showing 4 changed files with 529 additions and 357 deletions.
diff --git a/src/main/java/org/verapdf/rest/resources/ApiResource.java b/src/main/java/org/verapdf/rest/resources/ApiResource.java
@@ -1,11 +1,16 @@
 /**
- * 
+ *
  */
 package org.verapdf.rest.resources;
 
 import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.info.Info;
 import io.swagger.v3.oas.annotations.info.License;
+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;
 import io.swagger.v3.oas.annotations.servers.Server;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.verapdf.ReleaseDetails;
@@ -19,65 +24,81 @@
 
 /**
  * API wrapper resource, provides routing for child API resources.
- * 
+ *
  * @author <a href="mailto:[email protected]">Carl Wilson</a>.
  *         </p>
  *
  */
 @Path("/api")
 @Tag(name = "veraPDF")
 @OpenAPIDefinition(info = @Info(
-        title = "veraPDF API",
-        description = "Rest API for veraPDF",
-        version = "V0.2.0",
-        license = @License(name = "Apache 2.0", url = "https://www.apache.org/licenses/LICENSE-2.0")),
+		title = "veraPDF API",
+		description = "Rest API for veraPDF",
+		version = "V0.2.0",
+		license = @License(name = "Apache 2.0", url = "https://www.apache.org/licenses/LICENSE-2.0")),
                    servers = {@Server(url = "https://demo.verapdf.org", description = "default"),
                               @Server(url = "http://localhost:8080", description = "local")}
 )
 
 public final class ApiResource {
-    private static ReleaseDetails buildDetails = ReleaseDetails.addDetailsFromResource(
-            ReleaseDetails.APPLICATION_PROPERTIES_ROOT + "rest." + ReleaseDetails.PROPERTIES_EXT);
+	private static ReleaseDetails buildDetails = ReleaseDetails.addDetailsFromResource(
+			ReleaseDetails.APPLICATION_PROPERTIES_ROOT + "rest." + ReleaseDetails.PROPERTIES_EXT);
 
-    @GET
-    @Path("/")
-    @Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
-    public static ReleaseDetails getReleaseDetails() {
-        return buildDetails;
-    }
+	@GET
+	@Path("/")
+	@Operation(summary = "Get release details")
+	@ApiResponses(value = {
+			@ApiResponse(responseCode = "200", description = "OK", content = {
+					@Content(mediaType = "application/json", schema =
+					@Schema(implementation = ReleaseDetails.class)
+					), @Content(mediaType = "application/xml", schema =
+			@Schema(implementation = ReleaseDetails.class)
+			)})})
+	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
+	public static ReleaseDetails getReleaseDetails() {
+		return buildDetails;
+	}
 
-    /**
-     * @return the server environment information as a
-     *         {@link org.verapdf.rest.environment.Environment}.
-     */
-    @GET
-    @Path("/info")
-    @Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
-    public static Environment getEnvironment() {
-        return Environments.getEnvironment();
-    }
+	/**
+	 * @return the server environment information as a
+	 *         {@link org.verapdf.rest.environment.Environment}.
+	 */
+	@GET
+	@Path("/info")
+	@Operation(summary = "Get server environment information")
+	@ApiResponses(value = {
+			@ApiResponse(responseCode = "200", description = "OK", content = {
+					@Content(mediaType = "application/json", schema =
+					@Schema(implementation = ReleaseDetails.class)
+					), @Content(mediaType = "application/xml", schema =
+			@Schema(implementation = ReleaseDetails.class)
+			)})})
+	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
+	public static Environment getEnvironment() {
+		return Environments.getEnvironment();
+	}
 
-    /**
-     * @return a new {@link org.verapdf.rest.resources.ProfileResource}
-     */
-    @Path("/profiles")
-    public static ProfileResource getProfileResource() {
-        return new ProfileResource();
-    }
+	/**
+	 * @return a new {@link org.verapdf.rest.resources.ProfileResource}
+	 */
+	@Path("/profiles")
+	public static ProfileResource getProfileResource() {
+		return new ProfileResource();
+	}
 
-    /**
-     * @return a new {@link org.verapdf.rest.resources.ValidateResource}
-     */
-    @Path("/validate")
-    public static ValidateResource getValidateResource() {
-        return new ValidateResource();
-    }
+	/**
+	 * @return a new {@link org.verapdf.rest.resources.ValidateResource}
+	 */
+	@Path("/validate")
+	public static ValidateResource getValidateResource() {
+		return new ValidateResource();
+	}
 
-    /**
-     * @return a new {@link ByteStreamResource}
-     */
-    @Path("/sha1")
-    public static ByteStreamResource getBytestreamResource() {
-        return new ByteStreamResource();
-    }
+	/**
+	 * @return a new {@link ByteStreamResource}
+	 */
+	@Path("/sha1")
+	public static ByteStreamResource getBytestreamResource() {
+		return new ByteStreamResource();
+	}
 }
diff --git a/src/main/java/org/verapdf/rest/resources/ByteStreamResource.java b/src/main/java/org/verapdf/rest/resources/ByteStreamResource.java
@@ -1,76 +1,102 @@
 /**
- * 
+ *
  */
 package org.verapdf.rest.resources;
 
-import java.io.IOException;
-import java.io.InputStream;
-
-import javax.ws.rs.Consumes;
-import javax.ws.rs.GET;
-import javax.ws.rs.POST;
-import javax.ws.rs.Path;
-import javax.ws.rs.Produces;
-import javax.ws.rs.core.MediaType;
-
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterStyle;
+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;
 import org.glassfish.jersey.media.multipart.FormDataContentDisposition;
 import org.glassfish.jersey.media.multipart.FormDataParam;
 import org.openpreservation.bytestreams.ByteStreamId;
 import org.openpreservation.bytestreams.ByteStreams;
+import org.verapdf.ReleaseDetails;
+
+import javax.ws.rs.*;
+import javax.ws.rs.core.MediaType;
+import java.io.File;
+import java.io.IOException;
+import java.io.InputStream;
 
 
 /**
  * The REST resource definition for byte stream identification services, these
  * are JERSEY REST services and it's the annotations that perform the magic of
  * handling content types and serialisation.
- * 
+ *
  * @author <a href="mailto:[email protected]">Carl Wilson</a>.</p>
  */
 public class ByteStreamResource {
-    /**
-     * Default public constructor required by Jersey / Dropwizard
-     */
-    public ByteStreamResource() {
-        /** Intentionally blank */
-    }
+	/**
+	 * Default public constructor required by Jersey / Dropwizard
+	 */
+	public ByteStreamResource() {
+		/** Intentionally blank */
+	}
 
-    /**
-     * @param uploadedInputStream
-     *            InputStream for the uploaded file
-     * @param contentDispositionHeader
-     *            extra info about the uploaded file, currently unused.
-     * @return the {@link org.openpreservation.bytestreams.ByteStreamId} of
-     *         the uploaded file's byte stream serialised according to requested
-     *         content type.
-     */
-    @POST
-    @Consumes(MediaType.MULTIPART_FORM_DATA)
-    @Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML,
-            MediaType.TEXT_XML })
-    public static ByteStreamId getSha1(
-            @FormDataParam("file") InputStream uploadedInputStream,
-            @FormDataParam("file") final FormDataContentDisposition contentDispositionHeader) {
-        try {
-            ByteStreamId id = ByteStreams.idFromStream(uploadedInputStream);
-            uploadedInputStream.close();
-            return id;// return
-        } catch (IOException e) {
-            // TODO Auto-generated catch block
-            e.printStackTrace();
-        }
-        return ByteStreams.nullByteStreamId();
-    }
+	/**
+	 * @param uploadedInputStream
+	 *            InputStream for the uploaded file
+	 * @param contentDispositionHeader
+	 *            extra info about the uploaded file, currently unused.
+	 * @return the {@link org.openpreservation.bytestreams.ByteStreamId} of
+	 *         the uploaded file's byte stream serialised according to requested
+	 *         content type.
+	 */
+	@POST
+	@Operation(summary = "Upload file's byte stream and serialise according to requested content type")
+	@ApiResponses(value = {
+			@ApiResponse(responseCode = "200", description = "OK", content = {
+					@Content(mediaType = "application/xml", schema =
+					@Schema(implementation = ReleaseDetails.class)),
+					@Content(mediaType = "application/json", schema =
+					@Schema(implementation = ReleaseDetails.class)),
+					@Content(mediaType = "text/xml", schema =
+					@Schema(implementation = ReleaseDetails.class))
+			})})
+	@Consumes(MediaType.MULTIPART_FORM_DATA)
+	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML,
+	           MediaType.TEXT_XML})
+	public static ByteStreamId getSha1(
+			@Parameter(name = "file", schema = @Schema(implementation = File.class), style = ParameterStyle.FORM,
+			           description = "InputStream for the uploaded file")
+			@FormDataParam("file") InputStream uploadedInputStream,
+			@Parameter(hidden = true) @FormDataParam("file") final FormDataContentDisposition contentDispositionHeader) {
+		try {
+			ByteStreamId id = ByteStreams.idFromStream(uploadedInputStream);
+			uploadedInputStream.close();
+			return id;// return
+		} catch (IOException e) {
+			// TODO Auto-generated catch block
+			e.printStackTrace();
+		}
+		return ByteStreams.nullByteStreamId();
+	}
 
-    /**
-     * @return the {@link org.openpreservation.bytestreams} of
-     *         an empty (0 byte) byte stream serialised according to requested
-     *         content type.
-     */
-    @GET
-    @Path("/null")
-    @Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML,
-            MediaType.TEXT_XML })
-    public static ByteStreamId getEmptySha1() {
-        return ByteStreams.nullByteStreamId();
-    }
+	/**
+	 * @return the {@link org.openpreservation.bytestreams} of
+	 *         an empty (0 byte) byte stream serialised according to requested
+	 *         content type.
+	 */
+	@GET
+	@Path("/null")
+	@Operation(summary = "Get byte streams of an empty byte stream serialised according to requested content type")
+	@ApiResponses(value = {
+			@ApiResponse(responseCode = "200", description = "OK", content = {
+					@Content(mediaType = "application/xml", schema =
+					@Schema(implementation = ReleaseDetails.class)),
+					@Content(mediaType = "application/json", schema =
+					@Schema(implementation = ReleaseDetails.class)),
+					@Content(mediaType = "text/xml", schema =
+					@Schema(implementation = ReleaseDetails.class))
+			})})
+	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML,
+	           MediaType.TEXT_XML})
+	public static ByteStreamId getEmptySha1() {
+		return ByteStreams.nullByteStreamId();
+	}
 }