add graphql query documentation

Author: andrewazores

schema/schema.graphql

@@ -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
 }
 

src/main/java/io/cryostat/graphql/ActiveRecordings.java

@@ -265,6 +265,7 @@ public ArchivedRecording doArchive(@Source ActiveRecording recording) throws Exc
         return recordingHelper.archiveRecording(ar, null);
     }
 
+    @Description("List and optionally filter active recordings belonging to a Target")
     public TargetNodes.ActiveRecordings active(
             @Source Recordings recordings, ActiveRecordingsFilter filter) {
         var out = new TargetNodes.ActiveRecordings();

src/main/java/io/cryostat/graphql/ArchivedRecordings.java

@@ -31,6 +31,7 @@
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 import io.smallrye.graphql.api.Nullable;
 import jakarta.inject.Inject;
+import org.eclipse.microprofile.graphql.Description;
 import org.eclipse.microprofile.graphql.GraphQLApi;
 import org.eclipse.microprofile.graphql.NonNull;
 import org.eclipse.microprofile.graphql.Query;
@@ -42,6 +43,7 @@ public class ArchivedRecordings {
     @Inject RecordingHelper recordingHelper;
 
     @Query("archivedRecordings")
+    @Description("List archived recordings")
     public TargetNodes.ArchivedRecordings listArchivedRecordings(ArchivedRecordingsFilter filter) {
         var r = new TargetNodes.ArchivedRecordings();
         r.data =
@@ -54,6 +56,7 @@ public TargetNodes.ArchivedRecordings listArchivedRecordings(ArchivedRecordingsF
         return r;
     }
 
+    @Description("List and optionally filter archived recordings belonging to a Target")
     public TargetNodes.ArchivedRecordings archived(
             @Source Recordings recordings, ArchivedRecordingsFilter filter) {
         var out = new TargetNodes.ArchivedRecordings();
@@ -71,12 +74,14 @@ public TargetNodes.ArchivedRecordings archived(
     }
 
     @NonNull
+    @Description("Delete an archived recording")
     public ArchivedRecording doDelete(@Source ArchivedRecording recording) {
         recordingHelper.deleteArchivedRecording(recording.jvmId(), recording.name());
         return recording;
     }
 
     @NonNull
+    @Description("Update the metadata associated with an archived recording")
     public ArchivedRecording doPutMetadata(
             @Source ArchivedRecording recording, MetadataLabels metadataInput) {
         recordingHelper.updateArchivedRecordingMetadata(

src/main/java/io/cryostat/graphql/TargetNodes.java

@@ -79,6 +79,7 @@ public List<DiscoveryNode> getTargetNodes(DiscoveryNodeFilter filter) {
     }
 
     @Transactional
+    @Description("Retrieve a list of active recordings currently available on the target")
     public ActiveRecordings activeRecordings(
             @Source Target target, @Nullable ActiveRecordingsFilter filter) {
         var fTarget = Target.getTargetById(target.id);
@@ -93,6 +94,7 @@ public ActiveRecordings activeRecordings(
         return recordings;
     }
 
+    @Description("Retrieve a list of archived recordings belonging to the target")
     public ArchivedRecordings archivedRecordings(
             @Source Target target, @Nullable ArchivedRecordingsFilter filter) {
         var fTarget = Target.getTargetById(target.id);
@@ -107,6 +109,13 @@ public ArchivedRecordings archivedRecordings(
         return recordings;
     }
 
+    @Description(
+            """
+            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.
+            """)
     public Uni<Report> report(@Source Target target) {
         var fTarget = Target.getTargetById(target.id);
         return reportAggregator