Documentation update for endpoints, trdm, api gateway, and plugin use

transcom · Nov 2, 2023 · efdcbc3 · efdcbc3
1 parent f3f10ce
commit efdcbc3
Show file tree

Hide file tree

Showing 3 changed files with 153 additions and 13 deletions.
diff --git a/README.md b/README.md
@@ -1,3 +1,28 @@
+# Table of Contents
+- [Table of Contents](#table-of-contents)
+- [API Gateway](#api-gateway)
+- [trdm-lambda](#trdm-lambda)
+  - [Pre-Requisites](#pre-requisites)
+    - [Build](#build)
+    - [Run Application Locally](#run-application-locally)
+  - [Deploy](#deploy)
+  - [ENV variables](#env-variables)
+    - [Environment Specific Yaml files](#environment-specific-yaml-files)
+  - [Application Information](#application-information)
+    - [Meta Annotations](#meta-annotations)
+    - [Controller Advice](#controller-advice)
+    - [Custom Properties](#custom-properties)
+  - [Endpoints](#endpoints)
+    - [lastTableUpdate](#lasttableupdate)
+    - [getTable](#gettable)
+- [Apache CXF Code Generation](#apache-cxf-code-generation)
+  - [Plugin](#plugin)
+  - [Known Issue](#known-issue)
+- [TRDM](#trdm)
+
+# API Gateway
+Please see documentation [here](https://dp3.atlassian.net/wiki/spaces/MT/pages/2275573761/TRDM+Soap+Proxy+API+Gateway+Lambda+Function).
+
 # trdm-lambda
 Provides a serverless Java application to host an internal RESTful interface. This Java application will handle SOAP-based requests toward TRDM on behalf of our Go MilMove server. It will be hosted as an AWS Lambda function for MilMove API requests to TRDM via SOAP.
 
@@ -12,18 +37,21 @@ To build the application ru `sam build` from the root directory or in the same d
 
 ### Run Application Locally
 
-To run the application locally run `sam local start-api`
+To run the application locally run `sam local start-api`. It will require AWS credentials to turn on, so either you need `/.aws/credentials` or if using
+aws-vault to manage your credentials you need to wrap your start command like so: `aws-vault exec transcom-gov-dev -- sam local start-api`.
+
+## Deploy
 
-### Deploy
+To deploy the application to AWS, download the latest release, upload it into the bucket under lambda builds -> trdm-soap-proxy -> Make a new version folder -> upload with proper encryption keys set.
 
-To deploy the application to AWS use `sam deploy`. Add the `--guided` flag to go through a guided deploy.
+After it has been uploaded into the bucket please update the `trdm_soap_proxy_version` variable in terraform [here](https://github.com/transcom/terraform-aws-app-environment) under `variables.tf`.
 
 
 ## ENV variables
 
 The `application.yml` can store configurations for your env variables. Which includes both secrets and configs.
 
-To add a new variable simply add it to the `application.yml` following the yaml syntax. Then create a new Java class under the `config` pacakge. `TrdmProps.java` is a good example to follow.
+To add a new variable simply add it to the `application.yml` following the yaml syntax. Then create a new Java class under the `config` package.
 
 If there is a prefix for the config, make sure to add it. Then add all the properties related to the config in this file.
 
@@ -41,15 +69,6 @@ If each env requires a different configuration create a new yaml file following
 
 [Spring documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/howto.html#howto.properties-and-configuration).
 
-## OpenAPI
-
-Swagger is only available in the local development environment. It is disabled in stg and production.
-
-To view the API definitions you can navigate to either:
-1. http://localhost:8080/swagger-ui/index.html - For the Swagger UI
-2. http://localhost:8080/v3/api-docs - For the JSON definition of the API
-
-
 ## Application Information
 
 This application utilizes several core Spring Features.
@@ -82,3 +101,71 @@ When adding custom properties to the application you can add them directly the t
 
 Then if you plan on reading them into the application create a `CustomPropProps.java` class to handle the custom props you are loading in.
 
+## Endpoints
+
+### lastTableUpdate
+[Go here](docs/lastTableUpdate.md)
+
+### getTable
+[Go here](docs/getTable.md)
+
+# Apache CXF Code Generation
+It is very important to understand the backbone of the SOAP envelope generation. By using the `cxf-codegen-plugin` we can provide a WSDL and it will auto generate us code under `target` that can be used to generate SOAP envelopes.
+
+## Plugin
+
+```
+<plugin>
+    <groupId>org.apache.cxf</groupId>
+    <artifactId>cxf-codegen-plugin</artifactId>
+    <version>4.0.3</version>
+    <executions>
+        <execution>
+            <id>generate-sources</id>
+            <phase>generate-sources</phase>
+            <configuration>
+                <sourceRoot>${project.build.directory}/generated-sources/cxf</sourceRoot>
+                <wsdlOptions>
+                    <wsdlOption>
+                        <wsdl>${project.basedir}/src/main/resources/ReturnTableV7.wsdl</wsdl>
+                    </wsdlOption>
+                </wsdlOptions>
+            </configuration>
+            <goals>
+                <goal>wsdl2java</goal>
+            </goals>
+        </execution>
+    </executions>
+</plugin>
+```
+
+## Known Issue
+The issue with this and why we no longer have the plugin generating code at runtime is that during CI/CD this plugin generates files with hard code file references. This does not play well during compiling as the filenames will use hard coded references to the CircleCI file structure. That is why you can find the ReturnTableV7 code generated and added to our src [here](src/main/java/cxf).
+
+After the code was generated and plugged into `src`, we had to manually modify the WSDL references. See examples when you search that directory and sub directories for `classpath:ReturnTableV7.wsdl` - before these were class paths they were file references with hard coded CircleCI values - hence why when it was hosted into AWS Lambda it couldn't find the CircleCI directories.
+
+Additionally, the following static code was needed to grab the WSDL for the class.
+
+```
+static {
+    URL url = ReturnTable.class.getClassLoader().getResource("ReturnTableV7.wsdl");
+    if (url == null) {
+        java.util.logging.Logger.getLogger(ReturnTable.class.getName())
+            .log(java.util.logging.Level.INFO,
+                "Can not initialize the default wsdl from {0}", "classpath:ReturnTableV7.wsdl");
+    }
+    WSDL_LOCATION = url;
+}
+```
+
+**In short**, we generated the code with that plugin, imported it into the repository, and manually modified the WSDL file refs to be based on the classpath. Additionally, the imports within the services had to be imported like so:
+
+`import cxf.trdm.returntableservice.ReturnTable;` 
+
+Instead of relying on the target that gets auto generated with the plugin.
+
+
+# TRDM
+We are leveraging the `ReturnTableV7` WSDL provided by TRDM. This file has been verified to be unclassified in its entirety, holding no sensitive information and cleared to release into our open source repository by their administrators.
+
+Please see back to the [code generation](#apache-cxf-code-generation) section as to how this WSDL is so important for our function.
diff --git a/docs/getTable.md b/docs/getTable.md
@@ -0,0 +1,28 @@
+[Back to README](README.md)
+
+# Get Table
+
+`POST {ApiGatewayURL}/api/v1/getTable`
+
+## Notice
+It is strongly recommended to provide the contentUpdatedSinceDateTime in your request. Please leverage the last updated time within the database.
+
+## Controller
+[src/main/java/com/milmove/trdmlambda/milmove/controller/GetTableController.java](src/main/java/com/milmove/trdmlambda/milmove/controller/GetTableController.java)
+
+## Models
+[Request Model](src/main/java/com/milmove/trdmlambda/milmove/model/gettable/GetTableRequest.java)
+
+[Response Model](src/main/java/com/milmove/trdmlambda/milmove/model/gettable/GetTableResponse.java)
+
+Example
+```
+{
+    "physicalName": "{{TableName}}",
+    "contentUpdatedSinceDateTime":"{{now}}",
+    "returnContent": true
+}
+```
+
+#### HTTP Response Codes
+`[200, 400, 500, 502]`
diff --git a/docs/lastTableUpdate.md b/docs/lastTableUpdate.md
@@ -0,0 +1,25 @@
+[Back to README](README.md)
+
+
+# Last Table Update
+
+`POST {ApiGatewayURL}/api/v1/lastTableUpdate`
+
+## Controller
+[src/main/java/com/milmove/trdmlambda/milmove/controller/LastTableUpdateController.java](src/main/java/com/milmove/trdmlambda/milmove/controller/LastTableUpdateController.java)
+
+## Models
+
+[Request Model](src/main/java/com/milmove/trdmlambda/milmove/model/lasttableupdate/LastTableUpdateRequest.java)
+
+[Response Model](src/main/java/com/milmove/trdmlambda/milmove/model/lasttableupdate/LastTableUpdateResponse.java)
+
+Example
+```
+{
+    "physicalName": "{{TableName}}"
+}
+```
+
+## HTTP Response Codes
+`[200, 502]`