Merge pull request FASP-QAT#13 from decode-development/springdoc

Add SpringDoc Swagger endpoint and documentation

Set up SpringDoc to enable Swagger UI for local API exploration
and testing. This allows interactive API testing with the Swagger
UI at /swagger-ui.html and OpenAPI spec download in JSON 
(/api-docs) or YAML (/api-docs.yaml) format which will be used 
to generate API documentation.

Added OpenAPI annotations to JwtAuthenticationRestController to
support authentication through the Swagger UI, which is needed
to use the other endpoints.

Added API documentation to the REST endpoints to enable us to use
Swagger effectively.

Author: timler

.gitignore

@@ -38,4 +38,13 @@ src/main/resources/fasp - db design2.mwb.bak
 /target/
 docs/
 HELP.md
-README.md
+README.md
+
+# Mac
+.DS_Store
+
+# JEnv
+.java-version
+
+# VS Code
+.vscode

pom.xml

@@ -98,13 +98,8 @@
         </dependency>
         <dependency>
             <groupId>org.springdoc</groupId>
-            <artifactId>springdoc-openapi-ui</artifactId>
-            <version>1.3.1</version>
-        </dependency>
-        <dependency>
-            <groupId>org.springdoc</groupId>
-            <artifactId>springdoc-openapi-data-rest</artifactId>
-            <version>1.3.1</version>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+            <version>2.3.0</version>
         </dependency>
         <!-- API, java.xml.bind module -->
         <dependency>

src/main/java/cc/altius/FASP/ARTMIS/controller/ExportOrderIdsCsv.java

@@ -26,12 +26,18 @@
 import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.ResponseBody;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.Operation;
 
 /**
  *
  * @author altius
  */
 @Controller
+@Tag(
+    name = "Export Order IDs",
+    description = "Export Order IDs to CSV"
+)
 public class ExportOrderIdsCsv {
 
     @Autowired
@@ -50,6 +56,7 @@ public class ExportOrderIdsCsv {
 
     @RequestMapping(value = "/exportOrderData")
     @ResponseBody
+    @Operation(summary = "Export order data", description = "Export order data")
 //    @Scheduled(cron = "0 0 21 * * MON-FRI",zone="EST")
 //    @Scheduled(cron = "00 */02 * * * *")
     public String exportOrderData() {

src/main/java/cc/altius/FASP/ARTMIS/controller/ExportProgramCsv.java

@@ -26,12 +26,17 @@
 import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.ResponseBody;
-
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.Operation;
 /**
  *
  * @author altius
  */
 @Controller
+@Tag(
+    name = "Export Programs",
+    description = "Export Programs to CSV"
+)
 public class ExportProgramCsv {
 
     @Autowired
@@ -50,6 +55,7 @@ public class ExportProgramCsv {
 
     @RequestMapping(value = "/exportProgramData")
     @ResponseBody
+    @Operation(summary = "Export program data", description = "Export program data")
 //    @Scheduled(cron = "0 0 21 * * MON-FRI",zone="EST")
 //    @Scheduled(cron = "00 */02 * * * *")
     public String exportProgramCsv() {

src/main/java/cc/altius/FASP/ARTMIS/controller/ExportShipmentLinkingCsv.java

@@ -6,7 +6,6 @@
 package cc.altius.FASP.ARTMIS.controller;
 
 import cc.altius.FASP.ARTMIS.service.ExportArtmisDataService;
-import cc.altius.FASP.model.DTO.ExportOrderDataDTO;
 import cc.altius.FASP.model.DTO.ExportShipmentLinkingDTO;
 import cc.altius.FASP.model.EmailTemplate;
 import cc.altius.FASP.model.Emailer;
@@ -27,12 +26,18 @@
 import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.ResponseBody;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.Operation;
 
 /**
  *
  * @author altius
  */
 @Controller
+@Tag(
+    name = "Export Shipment Linking",
+    description = "Export Shipment Linking to CSV"
+)
 public class ExportShipmentLinkingCsv {
 
     @Autowired
@@ -51,6 +56,7 @@ public class ExportShipmentLinkingCsv {
 
     @RequestMapping(value = "/exportShipmentLinkingData")
     @ResponseBody
+    @Operation(summary = "Export shipment linking data", description = "Export shipment linking data")
 //    @Scheduled(cron = "0 0 21 * * MON-FRI",zone="EST")
 //    @Scheduled(cron = "00 */02 * * * *")
     public String exportOrderData() {

src/main/java/cc/altius/FASP/ARTMIS/controller/ExportSupplyPlanJson.java

@@ -34,12 +34,18 @@
 import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.ResponseBody;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.Operation;
 
 /**
  *
  * @author akil
  */
 @Controller
+@Tag(
+    name = "Export Supply Plan",
+    description = "Export Supply Plan to JSON"
+)
 public class ExportSupplyPlanJson {
 
     @Autowired
@@ -62,6 +68,7 @@ public class ExportSupplyPlanJson {
 
     @GetMapping("/exportSupplyPlan")
     @ResponseBody
+    @Operation(summary = "Export supply plan", description = "Export supply plan")
     public String exportSupplyPlan(Authentication auth) {
         logger.info(" ################ Going to start Supply Plan export process ############## ");
         String newLine = "<br/>\n";
@@ -174,6 +181,7 @@ public String exportSupplyPlan(Authentication auth) {
 
     @GetMapping("/exportManualJson")
     @ResponseBody
+    @Operation(summary = "Export manual supply plan json", description = "Export manual supply plan json")
     public String exportManualJson(Authentication auth) {
         logger.info(" ################ Going to start Manual Json export process ############## ");
         String newLine = "<br/>\n";

src/main/java/cc/altius/FASP/ARTMIS/controller/ImportArtmisDataController.java

@@ -12,12 +12,17 @@
 import cc.altius.FASP.ARTMIS.service.ImportArtmisDataService;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RestController;
+import io.swagger.v3.oas.annotations.tags.Tag;
 
 /**
  *
  * @author altius
  */
 @RestController
+@Tag(
+    name = "Import Shipment Data",
+    description = "Import Shipment Data from ARTMIS"
+)
 public class ImportArtmisDataController {
 
     @Autowired

src/main/java/cc/altius/FASP/ARTMIS/controller/ImportProductCatalogueController.java

@@ -13,12 +13,17 @@
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.ResponseBody;
 import org.xml.sax.SAXException;
+import io.swagger.v3.oas.annotations.tags.Tag;
 
 /**
  *
  * @author altius
  */
 @Controller
+@Tag(
+    name = "Import Product Catalogue",
+    description = "Import Product Catalogue from ARTMIS"
+)
 public class ImportProductCatalogueController {
 
     @Autowired

src/main/java/cc/altius/FASP/OpenApiConfig.java

@@ -0,0 +1,54 @@
+package cc.altius.FASP;
+
+import io.swagger.v3.oas.models.Components;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.info.License;
+import io.swagger.v3.oas.models.security.SecurityRequirement;
+import io.swagger.v3.oas.models.security.SecurityScheme;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class OpenApiConfig {
+
+    private final String appName;
+    private final String appVersion;
+    private final String appDescription;
+    
+    public OpenApiConfig(
+        @Value("${info.app.name}") String appName,
+        @Value("${info.app.version}") String appVersion,
+        @Value("${info.app.description}") String appDescription) {
+        this.appName = appName;
+        this.appVersion = appVersion;
+        this.appDescription = appDescription;
+    }
+    
+    @Bean
+    public OpenAPI faspOpenAPI() {
+        final String securitySchemeName = "bearerAuth";
+        return new OpenAPI()
+                .addSecurityItem(new SecurityRequirement()
+                        .addList(securitySchemeName))
+                .components(new Components()
+                        .addSecuritySchemes(securitySchemeName,
+                                new SecurityScheme()
+                                        .name(securitySchemeName)
+                                        .type(SecurityScheme.Type.HTTP)
+                                        .scheme("bearer")
+                                        .bearerFormat("JWT")
+                                        .description(
+                                            "Enter the JWT token in the format: Bearer <token>")))
+
+                .info(new Info()
+                        .title(appName)
+                        .description(appDescription)
+                        .version(appVersion)
+                        .license(new License()
+                                .name("Apache License Version 2.0")
+                                .url("https://www.apache.org/licenses/LICENSE-2.0")));
+    }
+}

src/main/java/cc/altius/FASP/jwt/JWTWebSecurityConfig.java

@@ -81,6 +81,10 @@ public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
                         .requestMatchers(HttpMethod.GET, refreshPath).permitAll()
                         .requestMatchers(HttpMethod.GET, "/").permitAll()
                         .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()
+                        .requestMatchers("/v3/api-docs/**").permitAll()
+                        .requestMatchers("/v3/api-docs.yaml").permitAll()
+                        .requestMatchers("/swagger-ui/**").permitAll()
+                        .requestMatchers("/swagger-ui.html").permitAll()
                         .requestMatchers(
                                 "/error",
                                 "/api/logout",