docs(api): document API and classes (#908)

Author: andrewazores

schema/openapi.yaml

@@ -50,7 +50,9 @@ type Annotations {
 
 type ArchivedRecording {
   archivedTime: BigInteger!
+  "Delete an archived recording"
   doDelete: ArchivedRecording!
+  "Update the metadata associated with an archived recording"
   doPutMetadata(metadataInput: MetadataLabelsInput): ArchivedRecording!
   downloadUrl: String
   jvmId: String
@@ -160,6 +162,7 @@ type OperatingSystemMetrics {
 
 "Query root"
 type Query {
+  "List archived recordings"
   archivedRecordings(filter: ArchivedRecordingsFilterInput): ArchivedRecordings
   "Get all environment nodes in the discovery tree with optional filtering"
   environmentNodes(filter: DiscoveryNodeFilterInput): [DiscoveryNode]
@@ -177,7 +180,9 @@ type RecordingAggregateInfo {
 }
 
 type Recordings {
+  "List and optionally filter active recordings belonging to a Target"
   active(filter: ActiveRecordingsFilterInput): ActiveRecordings
+  "List and optionally filter archived recordings belonging to a Target"
   archived(filter: ArchivedRecordingsFilterInput): ArchivedRecordings
 }
 
@@ -226,10 +231,12 @@ type Suggestion {
 }
 
 type Target {
+  "Retrieve a list of active recordings currently available on the target"
   activeRecordings(filter: ActiveRecordingsFilterInput): ActiveRecordings
   agent: Boolean!
   alias: String!
   annotations: Annotations!
+  "Retrieve a list of archived recordings belonging to the target"
   archivedRecordings(filter: ArchivedRecordingsFilterInput): ArchivedRecordings
   connectUrl: String!
   "Create a new Flight Recorder Snapshot on the specified Target"
@@ -246,6 +253,12 @@ type Target {
   mbeanMetrics: MBeanMetrics
   "Get the active and archived recordings belonging to this target"
   recordings: Recordings
+  """
+  Retrieve an automated analysis report from the selected target(s). If there is no report currently
+  available then this request will not cause a report to be generated, and instead it will return an empty
+  result. Report generation may be an expensive operation, especially if many reports are to be generated at
+  once, and should not be triggered by broad GraphQL selections.
+  """
   report: Report
 }
 

schema/schema.graphql

@@ -25,6 +25,7 @@
 import jakarta.inject.Inject;
 import org.jboss.logging.Logger;
 
+/** Describes the current build of the application. Contains information about the VCS commit. */
 @ApplicationScoped
 public class BuildInfo {
 

src/main/java/io/cryostat/BuildInfo.java

@@ -15,6 +15,7 @@
  */
 package io.cryostat;
 
+/** Java constants corresponding to configuration keys set in application.properties. */
 public class ConfigProperties {
     public static final String AWS_BUCKET_NAME_ARCHIVES = "storage.buckets.archives.name";
     public static final String AWS_BUCKET_NAME_EVENT_TEMPLATES =

src/main/java/io/cryostat/ConfigProperties.java

@@ -23,6 +23,10 @@
 import io.quarkus.runtime.QuarkusApplication;
 import io.quarkus.runtime.annotations.QuarkusMain;
 
+/**
+ * Main application entrypoint. Perform any required early initialization tasks, then kick off the
+ * webserver.
+ */
 @QuarkusMain
 public class Cryostat {
 

src/main/java/io/cryostat/Cryostat.java

@@ -37,6 +37,14 @@
 import software.amazon.awssdk.services.s3.model.NoSuchKeyException;
 import software.amazon.awssdk.services.s3.model.S3Exception;
 
+/**
+ * Map uncaught exceptions at the endpoint level to REST responses. For example, without a
+ * corresponding exception mapper, an uncaught jakarta.persistence.NoResultException would result in
+ * the web server responding with an HTTP 500 Internal Server Error (the default behaviour for all
+ * uncaught exceptions). Defining a mapper for NoResultException allows the global behaviour to be
+ * overridden to an HTTP 404 Not Found response. Individual endpoints may still use standard
+ * try-catch handling to deal with NoResultExceptions in other ways as needed.
+ */
 public class ExceptionMappers {
 
     @Inject Logger logger;

src/main/java/io/cryostat/ExceptionMappers.java

@@ -37,8 +37,10 @@
 import jakarta.ws.rs.core.MediaType;
 import org.apache.commons.lang3.StringUtils;
 import org.eclipse.microprofile.config.inject.ConfigProperty;
+import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.jboss.logging.Logger;
 
+/** Status and configuration verification for the application. */
 @Path("")
 class Health {
 
@@ -70,6 +72,15 @@ class Health {
     @Blocking
     @Path("/health")
     @PermitAll
+    @Operation(
+            summary = "Check the overall status of the application",
+            description =
+                    """
+                    Returns a map indicating whether various external components (ex.
+                        jfr-datasource, grafana-dashboard) are configured and whether those
+                        components can be reached by the Cryostat application. Also includes
+                        application semantic version and build information.
+                    """)
     public ApplicationHealth health() {
         CompletableFuture<Boolean> datasourceAvailable = new CompletableFuture<>();
         CompletableFuture<Boolean> dashboardAvailable = new CompletableFuture<>();
@@ -113,12 +124,31 @@ public ApplicationHealth health() {
     @Blocking
     @Path("/health/liveness")
     @PermitAll
+    @Operation(
+            summary = "Check if the application is able to accept and respond to requests.",
+            description =
+                    """
+                    Performs a no-op on a worker thread. This is a simply check to determine if
+                    the application has available threads to service requests. HTTP 204 No Content
+                    is the only expected response. If the application is not live and no worker
+                    threads are available, then the client will never receive a response.
+                    """)
     public void liveness() {}
 
     @GET
     @Path("/api/v4/grafana_dashboard_url")
     @PermitAll
     @Produces({MediaType.APPLICATION_JSON})
+    @Operation(
+            summary =
+                    "Return the URL which users can visit to access the associated Grafana"
+                            + " dashboard instance.",
+            description =
+                    """
+                    Returns the URL for the associated Grafana dashboard instance. If there is an internally-accessible
+                    (for Cryostat) URL and an externally-accessible URL (for users) URL, the externally-accessible URL
+                    is preferred. If neither are configured then the response is an HTTP 400 Bad Request.
+                    """)
     public DashboardUrl grafanaDashboardUrl() {
         String url =
                 dashboardExternalURL.orElseGet(
@@ -130,6 +160,14 @@ public DashboardUrl grafanaDashboardUrl() {
     @Path("/api/v4/grafana_datasource_url")
     @PermitAll
     @Produces({MediaType.APPLICATION_JSON})
+    @Operation(
+            summary = "Return the URL to the associated jfr-datasource instance.",
+            description =
+                    """
+                    Returns the URL for the jfr-datasource instance which Cryostat is configured to use. This datasource
+                    accepts JFR file uploads from Cryostat and allows the Grafana dashboard to perform queries on the
+                    data within the recording file.
+                    """)
     public DatasourceUrl grafanaDatasourceUrl() {
         String url = datasourceURL.orElseThrow(() -> new BadRequestException());
         return new DatasourceUrl(url);

src/main/java/io/cryostat/Health.java

@@ -34,6 +34,7 @@
 import jakarta.ws.rs.ext.Provider;
 
 @Provider
+/** Filter incoming request bodies or outgoing response bodies to scrub particular content. */
 public class JsonRequestFilter implements ContainerRequestFilter {
 
     static final Set<String> disallowedFields = Set.of("id");

src/main/java/io/cryostat/JsonRequestFilter.java

@@ -20,6 +20,10 @@
 
 import org.apache.commons.io.input.ProxyInputStream;
 
+/**
+ * An InputStream which informs a provided {@link java.util.function.Consumer} about the number of
+ * bytes read each time a chunk is read from this stream.
+ */
 public class ProgressInputStream extends ProxyInputStream {
 
     private final Consumer<Integer> onUpdate;

src/main/java/io/cryostat/ProgressInputStream.java

@@ -35,6 +35,10 @@
 import software.amazon.awssdk.services.s3.model.CreateBucketRequest;
 import software.amazon.awssdk.services.s3.model.HeadBucketRequest;
 
+/**
+ * Utility for interacting with S3 object storage buckets. Use to ensure that the S3 object storage
+ * meets the application requirements, ex. that the expected buckets exist.
+ */
 @ApplicationScoped
 public class StorageBuckets {