Add Swagger Specification Generation from Annotations (opendcs#360)

* Swagger configuration in progress
* Fixed Jackson dependencies
* endpoint annotations
* DTO annotations, auth annotations
* Some endpoints annotated using openapi.json as reference
* Updated paths, removed invalid openapi.json location information
* Ordered ResourceExamples inner classes alphabetically, added role to decode endpoint, updated DTO annotation wording
* Reformatted annotations, updated examples, updated response codes
* Rename Timeseries group retrieval method to match endpoint usage
* Updated annotations on check endpoint, updated build.gradle, updated documentation
* Added Swagger doc generation to release workflow
* Remove legacy OpenAPI specification JSON

Author: zack-rma

.github/workflows/publish.yml

@@ -18,6 +18,8 @@ jobs:
         uses: gradle/[email protected]
       - name: Build
         run: ./gradlew build
+      - name: Generate OpenAPI
+        run: ./gradlew generateOpenAPI
       - name: Attach OpenDCS REST API WAR file
         run: |
           gh release upload ${{ github.event.release.tag_name }} opendcs-rest-api/build/libs/opendcs-rest-api-${{ github.event.release.tag_name }}.war --repo ${{ github.repository }}
@@ -28,3 +30,8 @@ jobs:
           gh release upload ${{ github.event.release.tag_name }} opendcs-web-client/build/libs/opendcs-web-client-${{ github.event.release.tag_name }}.war --repo ${{ github.repository }}
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Attach OpenAPI Specification
+        run: |
+            gh release upload ${{ github.event.release.tag_name }} opendcs-rest-api/build/swagger/opendcs-openapi.json --repo ${{ github.repository }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/swagger.yml

@@ -0,0 +1,34 @@
+name: Swagger/OpenAPI Specification Generation
+on:
+  push:
+    branches:
+      - main
+      - feature/task_cwms_support
+  pull_request:
+    branches:
+      - main
+      - feature/task_cwms_support
+permissions:
+  contents: write
+jobs:
+  build-api-spec:
+    name: Build OpenAPI Specification
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/[email protected]
+      - name: Set up JDK 17
+        uses: actions/[email protected]
+        with:
+          java-version: 17
+          distribution: 'temurin'
+      - name: Setup Gradle
+        uses: gradle/[email protected]
+      - name: Generate OpenAPI
+        run: ./gradlew generateOpenAPI
+      - name: Upload OpenAPI Specification
+        uses: actions/[email protected]
+        with:
+          name: openapi
+          path: ./**/build/swagger/opendcs-openapi.json
+          retention-days: 1
+          if-no-files-found: error

doc-source/Swagger-README.md

@@ -0,0 +1,91 @@
+# Swagger/OpenAPI Configuration
+
+The OpenAPI specification represents the structure and expected input and output values of the
+REST API.  
+
+It can be visualized and interacted with via the Swagger UI, which represents the API
+resources and their functionality in a user-friendly manner.
+
+## Getting Started
+
+To view the API specification, navigate to the Swagger UI located at:
+```
+https://[REST_API_URL]/odcsapi/swaggerui/index.html
+```
+
+On development machines running the REST API locally, this will be located at 
+```
+http://localhost:7000/odcsapi/swaggerui/index.html
+```
+
+## OpenAPI Specification Generation
+
+In order to provide multiple options for developers to interact with the API,
+the OpenAPI specification is generated in one of two ways.
+
+### Automated Generation
+To automatically generate the OpenAPI specification, initiate the `./gradlew run` Gradle task.
+
+The OpenAPI specification will be generated upon runtime and will be available at the Swagger UI
+endpoint mentioned above.
+
+The raw JSON or YAML for the specification can be found at 
+```
+http://localhost:7000/odcsapi/openapi.json
+```
+or 
+```
+http://localhost:7000/odcsapi/openapi.yaml
+```
+respectively.
+
+### Manual Generation
+
+For ease of use, a manual generation method has been developed to avoid the requirement of running
+the webserver. This method is useful for developers who are working on modifying the API specification and
+wish to quickly generate the OpenAPI specification to view changes.
+
+> [!TIP]
+> Generated JSON and YAML OpenAPI specifications can be viewed by copying the content of the file and pasting it into the [Swagger Editor](https://editor.swagger.io/).
+
+To manually generate the OpenAPI specification, run the `generateOpenAPI` Gradle task found within
+the `documentation` group. The default output format is JSON.
+
+The manually generated OpenAPI specification will be placed in the `/build/swagger` directory. The
+file will be named `opendcs-openapi.json`.
+
+To change the output format from the default JSON to YAML, edit the `gradle.properties` file in the
+opendcs-rest-api project root. Change the `outputFormat` parameter from
+`JSON` to `YAML`. The file will be located in the same location as the JSON file, but with the YAML
+file extension. To revert back to the JSON format, change the parameter value back to `JSON`.
+The default output format is JSON if no format is specified.
+
+To remove the generated OpenAPI specification, run the `./gradlew clean` Gradle task.
+
+## Annotations
+
+The OpenAPI specification is generated using annotations from the `io.swagger.core.v3:swagger-jaxrs2`
+library. These annotations are used to describe the API endpoints and request and response bodies. 
+This is done by annotating the `Resource` endpoint classes and the appropriate DTO classes, 
+located in the `org.opendcs.odcsapi.res` and `org.opendcs.odcsapi.beans` packages, respectively.
+
+> [!TIP] 
+> The available annotations and their usage can be found [here](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations).
+
+### Examples
+
+Example input data for the `POST` endpoints can be found in the
+[ResourceExamples](../opendcs-rest-api/src/main/java/org/opendcs/odcsapi/res/ResourceExamples.java) 
+class, located in the `org.opendcs.odcsapi.res` package. These examples provide various levels of 
+input data for the different endpoints, which can be useful for determining the expected input data 
+for each endpoint.
+
+To add new examples to the [ResourceExamples](../opendcs-rest-api/src/main/java/org/opendcs/odcsapi/res/ResourceExamples.java) class,
+add a `public static final String` constant with the JSON-formatted example data. 
+**Remember to escape special characters in the JSON data.**
+
+> [!IMPORTANT]  
+> Due to a limitation of the Swagger annotations implementation, the examples must be String constants.
+> As a result, the examples must be placed within the [ResourceExamples](../opendcs-rest-api/src/main/java/org/opendcs/odcsapi/res/ResourceExamples.java)
+class as a JSON-formatted String constant and referenced by the `@ExampleObject` annotations located 
+within the `@RequestBody` annotation of each relevant endpoint. 

gradle.properties.example

@@ -8,4 +8,7 @@
 #opendcs.db.password=
 
 ### Needed for running the testcontainers
-org.gradle.jvmargs=-Xmx4096m
+org.gradle.jvmargs=-Xmx4096m
+
+## For Generating the OpenDCS API Documentation
+outputFormat=JSON

gradle/libs.versions.toml

@@ -12,8 +12,9 @@ cwms-db-codegen = { strictly = "7.0.0-OpenDCS" }
 cwms-ratings = "1.1.0"
 monolith = { strictly = "2.0.2" }
 
-swagger = "2.2.24"
-swagger-ui = "5.17.14"
+swagger = "2.2.28"
+swagger-ui = "5.18.3"
+jackson = "2.18.2"
 glassfish-jaxb = "2.3.3"
 websocket = "1.1"
 selenium = "3.141.59"
@@ -58,17 +59,16 @@ jersey-hk2 = { module = "org.glassfish.jersey.inject:jersey-hk2", version.ref =
 postgresql = { module = "org.postgresql:postgresql", version.ref = "postgresql" }
 oracle-jdbc = { module = "com.oracle.database.jdbc:ojdbc8", version.ref = "oracle" }
 oracle-ucp = { module = "com.oracle.database.jdbc:ucp", version.ref = "oracle" }
-swagger-jaxrs2 = { module = "io.swagger.core.v3:swagger-jaxrs2-jakarta", version.ref = "swagger" }
+swagger-jaxrs2 = { module = "io.swagger.core.v3:swagger-jaxrs2", version.ref = "swagger" }
+jackson = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" }
+jackson-annotations = { module = "com.fasterxml.jackson.core:jackson-annotations", version.ref = "jackson" }
 jaxb-runtime = { module = "org.glassfish.jaxb:jaxb-runtime", version.ref = "glassfish-jaxb" }
 websocket = { module = "javax.websocket:javax.websocket-api", version.ref = "websocket" }
 selenium = { module = "org.seleniumhq.selenium:selenium-java", version.ref = "selenium" }
 nimbus = { module = "com.nimbusds:nimbus-jose-jwt", version.ref = "nimbus" }
 jwt = { module = "com.auth0:java-jwt", version.ref = "jwt" }
 auto-service = { module = "com.google.auto.service:auto-service", version.ref = "auto-service" }
 
-# webjars
-swagger-ui = { module = "org.webjars:swagger-ui", version.ref = "swagger-ui" }
-
 #Test Dependencies
 opendcs-integrationtesting-fixtures = { module = "org.opendcs:opendcs-integrationtesting-fixtures", version.ref = "opendcs"}
 junit-bom = { module = "org.junit:junit-bom", version.ref = "junit" }
@@ -98,6 +98,9 @@ org-flywaydb-flyway-core = { module = "org.flywaydb:flyway-core", version.ref =
 commons-lang = { module = "commons-lang:commons-lang", version.ref = "commons-lang" }
 jul-to-slf4j = { module = "org.slf4j:jul-to-slf4j", version = "2.0.16"}
 
+# webjars
+swagger-ui = { module ="org.webjars:swagger-ui", version.ref = "swagger-ui" }
+
 [bundles]
 tomcat = ["tomcat-embedded-core", "tomcat-embedded-jasper", "tomcat-jdbc"]
 jdbi = [ "org-jdbi3-core", "org-jdbi3-sqlobject", "org-jdbi3-postgres" ]

opendcs-integration-test/build.gradle

@@ -50,6 +50,8 @@ dependencies {
 
     testRuntimeOnly(libs.oracle.jdbc)
     testRuntimeOnly(libs.byte.buddy)
+    testRuntimeOnly(libs.jackson)             // for swagger compatibility
+    testRuntimeOnly(libs.jackson.annotations) // for swagger compatibility
     testRuntimeOnly(libs.postgresql)
     testRuntimeOnly(libs.byte.buddy)
 }

opendcs-rest-api/build.gradle

@@ -18,6 +18,7 @@ plugins {
     id "opendcs-rest-api.deps-conventions"
     id "opendcs-rest-api.publishing-conventions"
     id "war"
+    id "io.swagger.core.v3.swagger-gradle-plugin" version "2.2.28"
 }
 
 configurations {
@@ -43,9 +44,12 @@ dependencies {
     implementation(libs.json.jackson)
     implementation(libs.jersey.container.servlet)
     implementation(libs.nimbus)
+    implementation(libs.swagger.jaxrs2)
     implementation(libs.jwt)
     implementation(libs.jersey.hk2)
     implementation(libs.slf4j.api)
+    implementation(libs.jackson)
+    runtimeOnly(libs.jackson.annotations) // updated for swagger compatibility
     runtimeOnly(libs.jaxb.runtime)
     runtimeOnly(libs.postgresql)
     webjars(libs.swagger.ui)
@@ -73,7 +77,7 @@ dependencies {
 task extractWebJars(type: Copy) {
     from zipTree(configurations.webjars.singleFile)
 
-    into file("${project.layout.getBuildDirectory().get().getAsFile().toString()}/resources/main/swaggerui")
+    into file("src/main/webapp/swaggerui")
     includeEmptyDirs false
     eachFile {
         path -= ~/^.+?\/.+?\/.+?\/.+?\/.+?\//
@@ -116,3 +120,19 @@ if (JavaVersion.current() != JavaVersion.VERSION_1_8) {
         }
     }
 }
+
+// task to generate OpenAPI JSON file
+resolve {
+    classpath = sourceSets.main.runtimeClasspath
+    outputFileName = 'opendcs-openapi'
+    outputFormat = providers.gradleProperty('outputFormat').getOrElse('JSON')
+    prettyPrint = 'TRUE'
+    resourcePackages = ['org.opendcs.odcsapi.res', 'org.opendcs.odcsapi.beans', 'org.opendcs.odcsapi.sec']
+    outputDir = file('build/swagger/')
+}
+
+tasks.register('generateOpenAPI') {
+    group = "documentation"
+    description = "Generates the Swagger OpenAPI JSON file without running the application"
+    dependsOn('resolve')
+}

opendcs-rest-api/src/main/java/org/opendcs/odcsapi/beans/ApiAlgoParm.java

@@ -15,12 +15,22 @@
 
 package org.opendcs.odcsapi.beans;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "Represents an algorithm parameter with a role name and parameter type.")
 public final class ApiAlgoParm
 {
-	/** The role name -- must be unique within an algorithm. */
+	/**
+	 * The role name -- must be unique within an algorithm.
+	 */
+	@Schema(description = "The role name of the parameter, must be unique within an algorithm.", example = "input1")
 	private String roleName;
-	
-	/** The parameter type -- one of the constant codes defined herein. */
+
+	/**
+	 * The parameter type.
+	 */
+	@Schema(description = "The type of the parameter. Can be input (i), output (o), or can embed extra information.",
+			example = "i")
 	private String parmType;
 
 	public String getRoleName()

opendcs-rest-api/src/main/java/org/opendcs/odcsapi/beans/ApiAlgorithm.java

@@ -19,29 +19,58 @@
 import java.util.List;
 import java.util.Properties;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "Represents an algorithm configuration with properties, parameters, and associated scripts.")
 public final class ApiAlgorithm
 {
-	/** Surrogate key for this algorithm in the time series database.  */
+	/**
+	 * Surrogate key for this algorithm in the time series database.
+	 */
+	@Schema(description = "Unique numeric identifier for the algorithm.", example = "4")
 	private Long algorithmId = null;
 
-	/** Name of this algorithm */
+	/**
+	 * Name of this algorithm
+	 */
+	@Schema(description = "Name of the algorithm.", example = "ChooseOne")
 	private String name = null;
 
-	/** Fully qualified Java class name to execut this algorithm. */
+	/**
+	 * Fully qualified Java class name to execute this algorithm.
+	 */
+	@Schema(description = "Fully qualified Java class name used to execute the algorithm.",
+			example = "decodes.tsdb.algo.ChooseOne")
 	private String execClass = null;
 
-	/** Free form multi-line comment */
+	/**
+	 * Free form multi-line comment
+	 */
+	@Schema(description = "Description or comments about the algorithm.", example = "Given two inputs, "
+			+ "output the best one: If only one is present at the time-slice, output it. "
+			+ "If one is outside the specified upper or lower limit (see properties) output the other. "
+			+ "If both are acceptable, output the first one. Useful in situations where you have redundant sensors.")
 	private String description = null;
 
-	/** Properties associated with this algorithm. */
+	/**
+	 * Properties associated with this algorithm.
+	 */
+	@Schema(description = "Key-value pairs containing properties associated with the algorithm.")
 	private Properties props = new Properties();
-	
-	/** parameters to this algorithm */
+
+	/**
+	 * parameters to this algorithm
+	 */
+	@Schema(description = "List of parameters used by the algorithm.", implementation = ApiAlgoParm.class)
 	private List<ApiAlgoParm> parms = new ArrayList<>();
 
-	/** For use in the editor -- the number of computations using this algo. */
+	/**
+	 * For use in the editor -- the number of computations using this algo.
+	 */
+	@Schema(description = "Number of computations currently using this algorithm.", example = "1")
 	private int numCompsUsing = 0;
-	
+
+	@Schema(description = "List of scripts associated with the algorithm.", implementation = ApiAlgorithmScript.class)
 	private List<ApiAlgorithmScript> algoScripts = new ArrayList<>();
 
 	public Long getAlgorithmId()

opendcs-rest-api/src/main/java/org/opendcs/odcsapi/beans/ApiAlgorithmRef.java

@@ -31,18 +31,31 @@
  */
 package org.opendcs.odcsapi.beans;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 
 /**
  * This class holds the info for an algorithm in the on-screen list.
  */
+@Schema(description = "API Algorithm Reference DTO that holds the summary information of an algorithm.")
 public final class ApiAlgorithmRef
 {
+	@Schema(description = "Unique ID of the algorithm.", example = "4")
 	private Long algorithmId = null;
+
+	@Schema(description = "The name of the algorithm.", example = "Bridge Clearance")
 	private String algorithmName = "";
+
+	@Schema(description = "Fully qualified Java execution class for the algorithm.",
+			example = "decodes.tsdb.algo.BridgeClearance")
 	private String execClass = "";
+
+	@Schema(description = "The number of computations using this algorithm.", example = "2")
 	private int numCompsUsing = 0;
+
+	@Schema(description = "A brief description of the algorithm.",
+			example = "Computes bridge clearance by subtracting water level from con")
 	private String description = "";
-	
+
 	public Long getAlgorithmId()
 	{
 		return algorithmId;
@@ -83,6 +96,4 @@ public void setDescription(String description)
 	{
 		this.description = description;
 	}
-	
-	
 }