feat: describe reactor contracts for SDK generation

pom.xml

@@ -61,6 +61,8 @@
 		     cannot share a single property. -->
 		<jackson2.version>2.22.4</jackson2.version>
 		<jackson2.annotations.version>2.22</jackson2.annotations.version>
+		<!-- OpenAPI annotations for reactor contracts (AbstractReactor2); keep in step with Monolith's swagger.version -->
+		<swagger.version>2.2.30</swagger.version>
 		<guava.version>33.7.2-jre</guava.version>
 		<jackson3.version>3.1.8</jackson3.version>
 		<!-- Keep these security pins in sync with Monolith/pom.xml. -->
@@ -1989,6 +1991,13 @@
 			<artifactId>jackson-annotations</artifactId>
 			<version>${jackson2.annotations.version}</version>
 		</dependency>
+		<!-- Source: https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-annotations-jakarta -->
+		<!-- Annotations only: describes AbstractReactor2 inputs for the OpenAPI document Monolith exports -->
+		<dependency>
+			<groupId>io.swagger.core.v3</groupId>
+			<artifactId>swagger-annotations-jakarta</artifactId>
+			<version>${swagger.version}</version>
+		</dependency>
 		<!-- Source: https://mvnrepository.com/artifact/com.fasterxml.jackson.datatype/jackson-datatype-jsr310 -->
 		<dependency>
 			<groupId>com.fasterxml.jackson.datatype</groupId>

src/prerna/openapi/Internal.java

@@ -0,0 +1,56 @@
+/*******************************************************************************
+ * Copyright 2015 Defense Health Agency (DHA)
+ *
+ * If your use of this software does not include any GPLv2 components:
+ * 	Licensed under the Apache License, Version 2.0 (the "License");
+ * 	you may not use this file except in compliance with the License.
+ * 	You may obtain a copy of the License at
+ *
+ * 	  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 	Unless required by applicable law or agreed to in writing, software
+ * 	distributed under the License is distributed on an "AS IS" BASIS,
+ * 	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * 	See the License for the specific language governing permissions and
+ * 	limitations under the License.
+ * ----------------------------------------------------------------------------
+ * If your use of this software includes any GPLv2 components:
+ * 	This program is free software; you can redistribute it and/or
+ * 	modify it under the terms of the GNU General Public License
+ * 	as published by the Free Software Foundation; either version 2
+ * 	of the License, or (at your option) any later version.
+ *
+ * 	This program is distributed in the hope that it will be useful,
+ * 	but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * 	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * 	GNU General Public License for more details.
+ *******************************************************************************/
+package prerna.openapi;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a REST operation or a reactor as internal: it is published in the
+ * OpenAPI document as {@code "x-internal": true}, and every SDK generated from
+ * the document tags it so its users know not to rely on it. It still works for
+ * everyone; this is a warning, not access control.
+ * <p>
+ * Put it on a resource method, on a resource class (every operation in it), or on
+ * a reactor class. To leave something out of the document and
+ * the SDKs entirely, use swagger-core's {@code @Hidden} instead.
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE, ElementType.METHOD })
+public @interface Internal {
+
+	/**
+	 * Why it is internal, such as "Used by the admin console only". It is shown to
+	 * SDK users next to the internal tag.
+	 */
+	String value() default "";
+}

src/prerna/openapi/PixelInput.java

@@ -0,0 +1,85 @@
+/*******************************************************************************
+ * Copyright 2015 Defense Health Agency (DHA)
+ *
+ * If your use of this software does not include any GPLv2 components:
+ * 	Licensed under the Apache License, Version 2.0 (the "License");
+ * 	you may not use this file except in compliance with the License.
+ * 	You may obtain a copy of the License at
+ *
+ * 	  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 	Unless required by applicable law or agreed to in writing, software
+ * 	distributed under the License is distributed on an "AS IS" BASIS,
+ * 	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * 	See the License for the specific language governing permissions and
+ * 	limitations under the License.
+ * ----------------------------------------------------------------------------
+ * If your use of this software includes any GPLv2 components:
+ * 	This program is free software; you can redistribute it and/or
+ * 	modify it under the terms of the GNU General Public License
+ * 	as published by the Free Software Foundation; either version 2
+ * 	of the License, or (at your option) any later version.
+ *
+ * 	This program is distributed in the hope that it will be useful,
+ * 	but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * 	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * 	GNU General Public License for more details.
+ *******************************************************************************/
+package prerna.openapi;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Refines what is inferred for one of a reactor's inputs. Every input in
+ * {@code keysToGet} is published without it; use it where the inferred type,
+ * description or requiredness is not good enough.
+ *
+ * <pre>{@code
+ * @PixelInput(name = "value", type = Object.class)
+ * @PixelInput(name = "limit", type = Integer.class, required = Requirement.OPTIONAL)
+ * public class EchoReactor extends AbstractReactor {
+ * }</pre>
+ *
+ * Naming a key the reactor does not declare fails the OpenAPI export.
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+@Repeatable(PixelInputs.class)
+public @interface PixelInput {
+
+	/** Whether an input must be passed. */
+	enum Requirement {
+		/** As {@code keyRequired} says. */
+		INFERRED,
+		/** It must be passed. */
+		REQUIRED,
+		/** It may be left out. */
+		OPTIONAL
+	}
+
+	/** The input's key, as in {@code keysToGet} (the canonical name, before any alias). */
+	String name();
+
+	/**
+	 * Its type: {@code String}, {@code Integer}, {@code Long}, {@code Double},
+	 * {@code Boolean}, an enum, {@code Map}, {@code List} (with {@link #items()}),
+	 * or {@code Object} for any value. {@code Void}, the default, keeps the
+	 * type inferred from {@code getKeyTypeForMCP}.
+	 */
+	Class<?> type() default Void.class;
+
+	/** The element type when {@link #type()} is {@code List}. */
+	Class<?> items() default Void.class;
+
+	/** Its description. Empty, the default, keeps {@code getDescriptionForKey}. */
+	String description() default "";
+
+	/** Whether it must be passed. {@code INFERRED}, the default, follows {@code keyRequired}. */
+	Requirement required() default Requirement.INFERRED;
+}

src/prerna/openapi/PixelInputs.java

@@ -0,0 +1,42 @@
+/*******************************************************************************
+ * Copyright 2015 Defense Health Agency (DHA)
+ *
+ * If your use of this software does not include any GPLv2 components:
+ * 	Licensed under the Apache License, Version 2.0 (the "License");
+ * 	you may not use this file except in compliance with the License.
+ * 	You may obtain a copy of the License at
+ *
+ * 	  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 	Unless required by applicable law or agreed to in writing, software
+ * 	distributed under the License is distributed on an "AS IS" BASIS,
+ * 	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * 	See the License for the specific language governing permissions and
+ * 	limitations under the License.
+ * ----------------------------------------------------------------------------
+ * If your use of this software includes any GPLv2 components:
+ * 	This program is free software; you can redistribute it and/or
+ * 	modify it under the terms of the GNU General Public License
+ * 	as published by the Free Software Foundation; either version 2
+ * 	of the License, or (at your option) any later version.
+ *
+ * 	This program is distributed in the hope that it will be useful,
+ * 	but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * 	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * 	GNU General Public License for more details.
+ *******************************************************************************/
+package prerna.openapi;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Holds repeated {@link PixelInput} annotations. */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface PixelInputs {
+	PixelInput[] value();
+}

src/prerna/openapi/PixelOutput.java

@@ -0,0 +1,63 @@
+/*******************************************************************************
+ * Copyright 2015 Defense Health Agency (DHA)
+ *
+ * If your use of this software does not include any GPLv2 components:
+ * 	Licensed under the Apache License, Version 2.0 (the "License");
+ * 	you may not use this file except in compliance with the License.
+ * 	You may obtain a copy of the License at
+ *
+ * 	  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 	Unless required by applicable law or agreed to in writing, software
+ * 	distributed under the License is distributed on an "AS IS" BASIS,
+ * 	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * 	See the License for the specific language governing permissions and
+ * 	limitations under the License.
+ * ----------------------------------------------------------------------------
+ * If your use of this software includes any GPLv2 components:
+ * 	This program is free software; you can redistribute it and/or
+ * 	modify it under the terms of the GNU General Public License
+ * 	as published by the Free Software Foundation; either version 2
+ * 	of the License, or (at your option) any later version.
+ *
+ * 	This program is distributed in the hope that it will be useful,
+ * 	but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * 	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * 	GNU General Public License for more details.
+ *******************************************************************************/
+package prerna.openapi;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Declares what a reactor returns, so the SDKs can type its output. Without it
+ * the output is published as any value: a reactor's code does not say what it
+ * returns, so it cannot be inferred.
+ *
+ * <pre>{@code
+ * @PixelOutput(value = String.class, description = "The id of the current insight")
+ * public class GetCurrentInsightIdReactor extends AbstractReactor {
+ * }</pre>
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface PixelOutput {
+
+	/**
+	 * The type of the output: {@code String}, {@code Integer}, {@code Long},
+	 * {@code Double}, {@code Boolean}, an enum, {@code Map}, {@code List} (with
+	 * {@link #items()}), a record, or {@code Object} for any value.
+	 */
+	Class<?> value();
+
+	/** The element type when {@link #value()} is {@code List}. */
+	Class<?> items() default Void.class;
+
+	/** What the output is. */
+	String description() default "";
+}

src/prerna/reactor/EchoReactor.java

@@ -27,11 +27,13 @@
  *******************************************************************************/
 package prerna.reactor;
 
+import prerna.openapi.PixelInput;
 import prerna.sablecc2.om.GenRowStruct;
 import prerna.sablecc2.om.PixelDataType;
 import prerna.sablecc2.om.ReactorKeysEnum;
 import prerna.sablecc2.om.nounmeta.NounMetadata;
 
+@PixelInput(name = "value", type = Object.class)
 public class EchoReactor extends AbstractReactor {
 
 	public EchoReactor() {