Add Swagger and OpenAPI description

Issue-ID: SDC-3185
Signed-off-by: Piotr Marcinkiewicz <piotr.marcinkiewicz@nokia.com>
Change-Id: Ib6371ec21ad8331124efd1fd15d2e82364c10e39

8 files changed, 113 insertions, 7 deletions

diff --git a/src/main/java/org/onap/sdc/helmvalidator/HelmValidatorApplication.java b/src/main/java/org/onap/sdc/helmvalidator/HelmValidatorApplication.java
index 0d094f6..4a51a2d 100644
--- a/src/main/java/org/onap/sdc/helmvalidator/HelmValidatorApplication.java
+++ b/src/main/java/org/onap/sdc/helmvalidator/HelmValidatorApplication.java
@@ -20,8 +20,8 @@
 
 package org.onap.sdc.helmvalidator;
 
-import org.onap.sdc.helmvalidator.config.LoggerConfig;
 import org.onap.sdc.helmvalidator.config.EnvProvider;
+import org.onap.sdc.helmvalidator.config.LoggerConfig;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.boot.builder.SpringApplicationBuilder;
 
diff --git a/src/main/java/org/onap/sdc/helmvalidator/api/SupportedVersionsController.java b/src/main/java/org/onap/sdc/helmvalidator/api/SupportedVersionsController.java
index 1a92624..8356b3d 100644
--- a/src/main/java/org/onap/sdc/helmvalidator/api/SupportedVersionsController.java
+++ b/src/main/java/org/onap/sdc/helmvalidator/api/SupportedVersionsController.java
@@ -20,9 +20,16 @@
 
 package org.onap.sdc.helmvalidator.api;
 
+import io.swagger.v3.oas.annotations.Operation;
+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.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
+import org.onap.sdc.helmvalidator.errorhandling.ValidationErrorResponse;
 import org.onap.sdc.helmvalidator.helm.versions.SupportedVersionsProvider;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpStatus;
@@ -31,6 +38,7 @@ import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RestController;
 
 @RestController
+@Tag(name = "VersionsService")
 public class SupportedVersionsController {
 
     private final SupportedVersionsProvider versionsProvider;
@@ -40,13 +48,19 @@ public class SupportedVersionsController {
         this.versionsProvider = provider;
     }
 
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "Supported Helm versions successfully returned",
+            content = @Content(schema = @Schema(ref = "#/components/schemas/VersionsResponse"))),
+        @ApiResponse(responseCode = "500", description = "Something went wrong during getting Helm versions",
+            content = @Content(schema = @Schema(implementation = ValidationErrorResponse.class)))})
+    @Operation(summary = "Show Helm versions", description = "Web endpoint for showing supported Helm versions.",
+        tags = "VersionsService")
     @GetMapping("/versions")
     public ResponseEntity<Map<String, List<String>>> supportedVersions() {
         return mapVersionsToResponseEntity(versionsProvider.getVersions());
     }
 
     private ResponseEntity<Map<String, List<String>>> mapVersionsToResponseEntity(List<String> versions) {
-
         return new ResponseEntity<>(Collections.singletonMap("versions", versions), HttpStatus.OK);
     }
 }
diff --git a/src/main/java/org/onap/sdc/helmvalidator/api/ValidationController.java b/src/main/java/org/onap/sdc/helmvalidator/api/ValidationController.java
index a4e476c..7fe57fb 100644
--- a/src/main/java/org/onap/sdc/helmvalidator/api/ValidationController.java
+++ b/src/main/java/org/onap/sdc/helmvalidator/api/ValidationController.java
@@ -20,19 +20,30 @@
 
 package org.onap.sdc.helmvalidator.api;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+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.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.onap.sdc.helmvalidator.errorhandling.ValidationErrorResponse;
 import org.onap.sdc.helmvalidator.helm.validation.ValidationService;
 import org.onap.sdc.helmvalidator.helm.validation.model.ValidationResult;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RequestPart;
 import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
 @RestController
+@Tag(name = "ValidationService")
 public class ValidationController {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ValidationController.class);
@@ -53,11 +64,27 @@ public class ValidationController {
      * @param isStrictLinted flag deciding if chart should be linted with strict option turned on
      * @return Response with result of validation
      */
-    @PostMapping("/validate")
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "Helm chart successfully validated",
+            content = @Content(schema = @Schema(implementation = ValidationResult.class))),
+        @ApiResponse(responseCode = "400", description = "Chart cannot be validated using selected version",
+            content = @Content(schema = @Schema(implementation = ValidationErrorResponse.class))),
+        @ApiResponse(responseCode = "500", description = "Something went wrong during validation execution",
+            content = @Content(schema = @Schema(implementation = ValidationErrorResponse.class)))
+    })
+    @Operation(
+        summary = "Validate chart",
+        description = "Web endpoint for Helm charts validation.",
+        tags = "ValidationService")
+    @PostMapping(value = "/validate", produces = "application/json", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
     public ResponseEntity<ValidationResult> validate(
+        @Parameter(description = "Desired Helm version which should be used to validate the chart")
         @RequestParam(value = "versionDesired", required = false) String version,
-        @RequestParam("file") MultipartFile file,
+        @Parameter(description = "Helm chart that should be validated (packed in .tgz format)", required = true)
+        @RequestParam MultipartFile file,
+        @Parameter(description = "If false, there will be an attempt to render the chart without linting it first")
         @RequestParam(value = "isLinted", required = false, defaultValue = "false") boolean isLinted,
+        @Parameter(description = "Linting should be strict or not")
         @RequestParam(value = "isStrictLinted", required = false, defaultValue = "false") boolean isStrictLinted) {
         LOGGER.debug("Received file: {}, size: {}, helm version: {}",
             file.getOriginalFilename(), file.getSize(), version);
diff --git a/src/main/java/org/onap/sdc/helmvalidator/config/DocsConfiguration.java b/src/main/java/org/onap/sdc/helmvalidator/config/DocsConfiguration.java
new file mode 100644
index 0000000..dbf97af
--- /dev/null
+++ b/src/main/java/org/onap/sdc/helmvalidator/config/DocsConfiguration.java
@@ -0,0 +1,62 @@
+/*
+ * ============LICENSE_START=======================================================
+ * SDC-HELM-VALIDATOR
+ * ================================================================================
+ * Copyright (C) 2021 Nokia. All rights reserved.
+ * ================================================================================
+ * 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.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.sdc.helmvalidator.config;
+
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+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.media.ArraySchema;
+import io.swagger.v3.oas.models.media.Schema;
+import io.swagger.v3.oas.models.media.StringSchema;
+import java.util.List;
+import java.util.Map;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+@OpenAPIDefinition
+public class DocsConfiguration {
+
+    /**
+     * Create Open API definition.
+     *
+     * @return Custom Open API definition
+     */
+    @Bean
+    public OpenAPI customOpenApi() {
+        var versionsSchema = new Schema<Map<String, List<String>>>().addProperties("versions", getArraySchema());
+
+        return new OpenAPI().info(
+            new Info()
+                .title("OpenAPI definition for SDC Helm validator")
+                .version("v0")
+                .description("Application for validating Helm charts."))
+            .components(new Components()
+                .addSchemas("VersionsResponse", versionsSchema));
+    }
+
+    private ArraySchema getArraySchema() {
+        ArraySchema arraySchema = new ArraySchema();
+        arraySchema.setItems(new StringSchema());
+        return arraySchema;
+    }
+}
diff --git a/src/main/java/org/onap/sdc/helmvalidator/errorhandling/ValidationErrorResponse.java b/src/main/java/org/onap/sdc/helmvalidator/errorhandling/ValidationErrorResponse.java
index 0f1fded..20ff9a5 100644
--- a/src/main/java/org/onap/sdc/helmvalidator/errorhandling/ValidationErrorResponse.java
+++ b/src/main/java/org/onap/sdc/helmvalidator/errorhandling/ValidationErrorResponse.java
@@ -20,7 +20,7 @@
 
 package org.onap.sdc.helmvalidator.errorhandling;
 
-class ValidationErrorResponse {
+public class ValidationErrorResponse {
 
     private final String message;
 
diff --git a/src/main/resources/application.properties b/src/main/resources/application.properties
index f9dea88..f3f8498 100644
--- a/src/main/resources/application.properties
+++ b/src/main/resources/application.properties
@@ -7,3 +7,6 @@ logging.logback.rollingpolicy.max-file-size=1MB
 logging.logback.rollingpolicy.total-size-cap=10MB
 logging.logback.rollingpolicy.max-history=30
 logging.logback.rollingpolicy.clean-history-on-start=true
+
+springdoc.show-actuator=true
+springdoc.swagger-ui.path=/docs
diff --git a/src/test/java/org/onap/sdc/helmvalidator/HelmValidatorApplicationTests.java b/src/test/java/org/onap/sdc/helmvalidator/HelmValidatorApplicationTests.java
index 5efbedc..e58e92b 100644
--- a/src/test/java/org/onap/sdc/helmvalidator/HelmValidatorApplicationTests.java
+++ b/src/test/java/org/onap/sdc/helmvalidator/HelmValidatorApplicationTests.java
@@ -27,7 +27,7 @@ import org.springframework.boot.test.context.SpringBootTest;
 class HelmValidatorApplicationTests {
 
     @Test
-        // This method check Spring context load - it no requires assertion (Sonar rule java:S2699)
+    // This method check Spring context load - it no requires assertion (Sonar rule java:S2699)
     void contextLoads() { // NOSONAR
     }
 
diff --git a/src/test/java/org/onap/sdc/helmvalidator/helm/versions/ApiVersionsReaderTest.java b/src/test/java/org/onap/sdc/helmvalidator/helm/versions/ApiVersionsReaderTest.java
index 2dbb6c1..b7b6053 100644
--- a/src/test/java/org/onap/sdc/helmvalidator/helm/versions/ApiVersionsReaderTest.java
+++ b/src/test/java/org/onap/sdc/helmvalidator/helm/versions/ApiVersionsReaderTest.java
@@ -41,7 +41,7 @@ import org.onap.sdc.helmvalidator.helm.versions.exception.ReadFileException;
 
 class ApiVersionsReaderTest {
 
-    private static final String API_VERSION_V2= "v2";
+    private static final String API_VERSION_V2 = "v2";
     private static final String TEST_RESOURCES_TMP = "src/test/resources/tmp";
     private static final Path TEST_CHART_PATH = Path.of(TEST_RESOURCES_TMP).resolve(Path.of("Chart.yaml"));