feat: adding swagger

pom.xml

@@ -178,6 +178,48 @@
 							</warSourceIncludes>
 						</configuration>
 					</plugin>
+					<plugin>
+						<artifactId>maven-dependency-plugin</artifactId>
+						<version>2.10</version>
+					</plugin>
+    		<plugin>
+    		  <groupId>io.openapitools.swagger</groupId>
+    		  <artifactId>swagger-maven-plugin</artifactId>
+    		  <configuration>
+    		    <resourcePackages>
+    		      <resourcePackage>prerna.semoss.web.services.local</resourcePackage>
+				  <resourcePackage>prerna.semoss.web.services.local.auth</resourcePackage>
+    		    </resourcePackages>	
+    		    <outputDirectory>${basedir}/swagger-ui</outputDirectory>
+    		    <outputFilename>swagger</outputFilename>
+    		    <outputFormats>JSON,YAML</outputFormats>
+    		    <prettyPrint>true</prettyPrint>
+				    <swaggerConfig>
+    				  <servers>
+    				    <server>
+    				      <url>https://workshop.cfg.deloitte.com/cfg-ai-demo/Monolith/api</url>
+    				      <description>Demo Endpoint URL</description>
+    				    </server>
+    				    <server>
+    				      <url>http://localhost:8080/Monolith/api</url>
+    				      <description>Local Development</description>
+    				    </server>
+    				  </servers>
+    				  <info>
+    				    <title>AI Core</title>
+    				    <version>${project.version}</version>
+    				  </info>
+    				</swaggerConfig>
+    		  </configuration>
+    		  <executions>
+    		    <execution>
+    		      <goals>
+    		        <goal>generate</goal>
+    		      </goals>
+    		    </execution>
+    		  </executions>
+    		</plugin>
+
 				</plugins>
 			</build>
 		</profile>
@@ -352,6 +394,13 @@
 				</exclusion>
 			</exclusions>
 		</dependency>
+		<!-- OpenAPI Specification dependency -->
+		<dependency>
+			<groupId>io.swagger.core.v3</groupId>
+			<artifactId>swagger-core</artifactId>
+			<version>2.2.21</version>
+		</dependency>
+
 		<!-- https://mvnrepository.com/artifact/org.apache.tomcat/tomcat-catalina -->
 		<!-- this is the primary tomcat specific jar -->
 		<dependency>

src/prerna/semoss/web/services/config/AdminConfigService.java

@@ -1,4 +1,5 @@
 package prerna.semoss.web.services.config;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.io.IOException;
 import java.util.HashMap;
@@ -31,6 +32,7 @@
 import prerna.web.conf.AdminStartupFilter;
 import prerna.web.services.util.WebUtility;
 
+@SecurityRequirement(name = "basicAuth")
 @Path("/")
 @PermitAll
 public class AdminConfigService {

src/prerna/semoss/web/services/config/ServerConfigurationResource.java

@@ -1,4 +1,5 @@
 package prerna.semoss.web.services.config;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -39,6 +40,7 @@
 
 @Path("/config")
 @PermitAll
+@SecurityRequirement(name = "basicAuth")
 public class ServerConfigurationResource {
 
 	private static final Logger logger = LogManager.getLogger(ServerConfigurationResource.class); 

src/prerna/semoss/web/services/config/TrustedTokenService.java

@@ -1,4 +1,5 @@
 package prerna.semoss.web.services.config;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.io.IOException;
 import java.util.HashMap;
@@ -33,6 +34,7 @@
 
 @Path("/")
 @PermitAll
+@SecurityRequirement(name = "basicAuth")
 public class TrustedTokenService {
 
 	private static final Logger logger = LogManager.getLogger(TrustedTokenService.class);
@@ -70,6 +72,7 @@ public Response getTokenGet(@Context HttpServletRequest request, @Context HttpSe
 		return WebUtility.getResponse(retMap, 200);
 	}
 
+	@SecurityRequirement(name = "basicAuth")
 	@POST
 	@Path("/getToken")
 	public Response getTokenPost(@Context HttpServletRequest request, @Context HttpServletResponse response) throws IOException {

src/prerna/semoss/web/services/local/APIResource.java

@@ -50,6 +50,10 @@
 import org.apache.logging.log4j.Logger;
 import org.json.JSONObject;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
+import io.swagger.v3.oas.annotations.security.SecurityScheme;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import prerna.om.Insight;
 import prerna.om.InsightStore;
 import prerna.util.Constants;
@@ -58,6 +62,9 @@
 import prerna.web.services.util.WebUtility;
 
 @Path("/")
+@Tag(name = "API", description = "API for querying insights")
+@SecurityRequirement(name = "basicAuth")
+@SecurityScheme(name = "basicAuth", type = SecuritySchemeType.HTTP, scheme = "basic")
 public class APIResource {
 
 	private static final Logger logger = LogManager.getLogger(APIResource.class);

src/prerna/semoss/web/services/local/AuthorizationResource.java

@@ -42,10 +42,21 @@
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
+import io.swagger.v3.oas.annotations.security.SecurityScheme;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import prerna.auth.utils.SecurityQueryUtils;
 import prerna.web.services.util.WebUtility;
 
 @Path("/authorization")
+@Tag(name = "Authorization", description = "Authorization and user search APIs")
+@SecurityRequirement(name = "basicAuth")
+@SecurityScheme(name = "basicAuth", type = SecuritySchemeType.HTTP, scheme = "basic")
 public class AuthorizationResource {
 
 	private static final Logger classLogger = LogManager.getLogger(AuthorizationResource.class);
@@ -55,6 +66,18 @@ public class AuthorizationResource {
 	@GET
 	@Produces("application/json")
 	@Path("searchForUser")
+	@Operation(
+		summary = "Search for users",
+		description = "Searches for users by a case-insensitive search term.",
+		parameters = {
+			@Parameter(name = "searchTerm", description = "Search term to match against user attributes", required = true)
+		},
+		responses = {
+			@ApiResponse(responseCode = "200", description = "List of matched users", content = @Content(mediaType = "application/json")),
+			@ApiResponse(responseCode = "401", description = "Unauthorized"),
+			@ApiResponse(responseCode = "500", description = "Server error")
+		}
+	)
 	public StreamingOutput searchForUser(@Context HttpServletRequest request, @QueryParam("searchTerm") String searchTerm) {
 		List<Map<String, Object>> ret = SecurityQueryUtils.searchForUser(WebUtility.inputSQLSanitizer(searchTerm.trim()));
 		return WebUtility.getSO(ret);

src/prerna/semoss/web/services/local/EngineRouteResource.java

@@ -26,6 +26,13 @@
 import javax.ws.rs.core.Response;
 import javax.ws.rs.core.Response.ResponseBuilder;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import org.apache.commons.io.FilenameUtils;
 import org.apache.commons.io.filefilter.WildcardFileFilter;
 import org.apache.logging.log4j.LogManager;
@@ -49,6 +56,7 @@
 
 @Path("/e-{engineId}")
 @PermitAll
+@Tag(name = "Engine Route", description = "Per-engine endpoints for SMSS configuration updates and image download.")
 public class EngineRouteResource {
 
 	private static final Logger classLogger = LogManager.getLogger(ModelEngineResource.class);
@@ -73,6 +81,12 @@ private boolean canAccessOrDiscoverableEngine(User user, String engineId) throws
 	@POST
 	@Path("/updateSmssFile")
 	@Produces("application/json;charset=utf-8")
+	@Operation(summary = "Update engine SMSS file", description = "Updates the engine's SMSS configuration file with new content, preserving concealed sensitive values and validating immutable fields (engine id, name, type). Requires admin or engine owner.")
+	@ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "SMSS updated", content = @Content(schema = @Schema(implementation = Map.class))),
+        @ApiResponse(responseCode = "400", description = "Validation or processing error", content = @Content(schema = @Schema(implementation = Map.class))),
+        @ApiResponse(responseCode = "401", description = "Unauthorized or insufficient permissions", content = @Content(schema = @Schema(implementation = Map.class)))
+    })
 	public Response updateSmssFile(@Context HttpServletRequest request, @PathParam("engineId") String engineId) {
 		engineId = WebUtility.inputSanitizer(engineId);
 
@@ -197,6 +211,13 @@ public Response updateSmssFile(@Context HttpServletRequest request, @PathParam("
 	@GET
 	@Path("/image/download")
 	@Produces({MediaType.APPLICATION_OCTET_STREAM, MediaType.APPLICATION_SVG_XML})
+	@Operation(summary = "Download engine image", description = "Returns the engine image (PNG/JPEG/GIF/SVG). Supports ETag-based client caching. Falls back to generated default if none found.")
+	@ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "Image file returned"),
+        @ApiResponse(responseCode = "304", description = "Not modified (ETag match)"),
+        @ApiResponse(responseCode = "400", description = "Invalid engine or retrieval error", content = @Content(schema = @Schema(implementation = Map.class))),
+        @ApiResponse(responseCode = "401", description = "Unauthorized or no access", content = @Content(schema = @Schema(implementation = Map.class)))
+    })
 	public Response imageDownload(@Context final Request coreRequest, @Context HttpServletRequest request, @PathParam("engineId") String engineId) {
 		engineId=WebUtility.inputSanitizer(engineId);
 
@@ -313,6 +334,7 @@ private File findImageFile(String folderDirectory) {
 		extensions.add("image.jpg");
 		extensions.add("image.gif");
 		extensions.add("image.svg");
+		@SuppressWarnings("deprecation")
 		FileFilter imageExtensionFilter = new WildcardFileFilter(extensions);
 		File baseFolder = new File(WebUtility.normalizePath(folderDirectory));
 		File[] imageFiles = baseFolder.listFiles(imageExtensionFilter);

src/prerna/semoss/web/services/local/ExecuteInsightResource.java

@@ -1,4 +1,5 @@
 package prerna.semoss.web.services.local;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.util.HashMap;
 import java.util.List;
@@ -23,6 +24,7 @@
 import prerna.web.services.util.WebUtility;
 
 @Path("exec")
+@SecurityRequirement(name = "basicAuth")
 public class ExecuteInsightResource {
 
 	@Path("/test")

src/prerna/semoss/web/services/local/LegacyAppResource.java

@@ -1,4 +1,12 @@
 package prerna.semoss.web.services.local;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+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.tags.Tag;
 
 import java.io.File;
 import java.io.FileFilter;
@@ -52,6 +60,8 @@
 @Path("/app-{databaseId}")
 @PermitAll
 @Deprecated
+@SecurityRequirement(name = "basicAuth")
+@Tag(name = "Database Engine", description = "LEGACY endpoints for database operations. Deprecated: use /e-{engineId} or /database-{databaseId} endpoints instead.")
 // replaced by DatabaseResource
 public class LegacyAppResource {
 
@@ -76,6 +86,23 @@ private boolean canViewDatabase(User user, String databaseId) throws IllegalAcce
 	@POST
 	@Path("/updateSmssFile")
 	@Produces("application/json;charset=utf-8")
+	@Operation(
+		summary = "Update database SMSS file (legacy)",
+		description = "Updates the SMSS configuration file for the specified database. Deprecated: use /database-{databaseId} or /e-{engineId} equivalent.",
+		deprecated = true,
+		parameters = {
+			@Parameter(name = "databaseId", in = ParameterIn.PATH, required = true, description = "Database identifier")
+		},
+		responses = {
+			@ApiResponse(responseCode = "200", description = "SMSS file updated",
+				content = @Content(mediaType = "application/json",
+					schema = @Schema(implementation = LegacyUpdateResponse.class))),
+			@ApiResponse(responseCode = "400", description = "Bad request",
+				content = @Content(mediaType = "application/json")),
+			@ApiResponse(responseCode = "401", description = "Unauthorized",
+				content = @Content(mediaType = "application/json"))
+		}
+	)
 	public Response updateSmssFile(@Context HttpServletRequest request, @PathParam("databaseId") String databaseId) {
 		logger.warn("CALLING LEGACY ENDPOINT - NEED TO UPDATE TO DATABASE SPECIFIC ENDPOINT /database-{databaseId} OR GENERIC ENGINE ENDPOINT /e-{engineid}");
 		logger.warn("CALLING LEGACY ENDPOINT - NEED TO UPDATE TO DATABASE SPECIFIC ENDPOINT /database-{databaseId} OR GENERIC ENGINE ENDPOINT /e-{engineid}");
@@ -187,6 +214,26 @@ public Response updateSmssFile(@Context HttpServletRequest request, @PathParam("
 	@GET
 	@Path("/appImage/download")
 	@Produces({MediaType.APPLICATION_OCTET_STREAM, MediaType.APPLICATION_SVG_XML})
+	@Operation(
+		summary = "Download database image (legacy)",
+		description = "Downloads the database image for the specified database. Deprecated: use /e-{engineId}/image/download.",
+		deprecated = true,
+		parameters = {
+			@Parameter(name = "databaseId", in = ParameterIn.PATH, required = true, description = "Database identifier")
+		},
+		responses = {
+			@ApiResponse(responseCode = "200", description = "Image downloaded",
+				content = {
+					@Content(mediaType = "application/octet-stream", schema = @Schema(type = "string", format = "binary")),
+					@Content(mediaType = MediaType.APPLICATION_SVG_XML, schema = @Schema(type = "string", format = "binary"))
+				}
+			),
+			@ApiResponse(responseCode = "400", description = "Bad request",
+				content = @Content(mediaType = "application/json")),
+			@ApiResponse(responseCode = "401", description = "Unauthorized",
+				content = @Content(mediaType = "application/json"))
+		}
+	)
 	public Response imageDownload(@Context final Request coreRequest, @Context HttpServletRequest request, @PathParam("databaseId") String databaseId) {
 		logger.warn("CALLING LEGACY ENDPOINT - NEED TO UPDATE TO ENGINE ENDPOINT /e-{engineid}");
 		logger.warn("CALLING LEGACY ENDPOINT - NEED TO UPDATE TO ENGINE ENDPOINT /e-{engineid}");
@@ -341,3 +388,9 @@ protected void closeStream(FileInputStream fis) {
 		}
 	}
 }
+
+// DTOs for OpenAPI documentation of legacy responses
+class LegacyUpdateResponse {
+	@Schema(description = "Whether the operation succeeded")
+	public Boolean success;
+}