Add Swagger and OpenAPI description

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

11 files changed, 316 insertions, 7 deletions

diff --git a/OpenAPI.yaml b/OpenAPI.yaml
new file mode 100644
index 0000000..686d3e6
--- /dev/null
+++ b/OpenAPI.yaml
@@ -0,0 +1,191 @@
+openapi: 3.0.1
+info:
+  title: OpenAPI definition for SDC Helm validator
+  description: Application for validating Helm charts.
+  version: v0
+servers:
+  - url: 'http://localhost:8080'
+    description: Generated server url
+tags:
+  - name: Actuator
+    description: Monitor and interact
+    externalDocs:
+      description: Spring Boot Actuator Web API Documentation
+      url: 'https://docs.spring.io/spring-boot/docs/current/actuator-api/html/'
+paths:
+  /validate:
+    post:
+      tags:
+        - ValidationService
+      summary: Validate chart
+      description: Web endpoint for Helm charts validation.
+      operationId: validate
+      parameters:
+        - name: versionDesired
+          in: query
+          description: Desired Helm version which should be used to validate the chart
+          required: false
+          schema:
+            type: string
+        - name: isLinted
+          in: query
+          description: 'If false, there will be an attempt to render the chart without linting it first'
+          required: false
+          schema:
+            type: boolean
+            default: false
+        - name: isStrictLinted
+          in: query
+          description: Linting should be strict or not
+          required: false
+          schema:
+            type: boolean
+            default: false
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              required:
+                - file
+              type: object
+              properties:
+                file:
+                  type: string
+                  description: Helm chart that should be validated (packed in .tgz format)
+                  format: binary
+      responses:
+        '200':
+          description: Helm chart successfully validated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationResult'
+        '400':
+          description: Chart cannot be validated using selected version
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationErrorResponse'
+        '500':
+          description: Something went wrong during validation execution
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationErrorResponse'
+  /versions:
+    get:
+      tags:
+        - VersionsService
+      summary: Show Helm versions
+      description: Web endpoint for showing supported Helm versions.
+      operationId: supportedVersions
+      responses:
+        '200':
+          description: Supported Helm versions successfully returned
+          content:
+            '*/*':
+              schema:
+                $ref: '#/components/schemas/VersionsResponse'
+        '500':
+          description: Something went wrong during getting Helm versions
+          content:
+            '*/*':
+              schema:
+                $ref: '#/components/schemas/ValidationErrorResponse'
+  /actuator:
+    get:
+      tags:
+        - Actuator
+      summary: Actuator root web endpoint
+      operationId: links_0
+      responses:
+        '200':
+          description: OK
+          content:
+            '*/*':
+              schema:
+                type: object
+                additionalProperties:
+                  type: object
+                  additionalProperties:
+                    $ref: '#/components/schemas/Link'
+  /actuator/info:
+    get:
+      tags:
+        - Actuator
+      summary: Actuator web endpoint 'info'
+      operationId: handle_1
+      responses:
+        '200':
+          description: OK
+          content:
+            '*/*':
+              schema:
+                type: object
+  /actuator/health:
+    get:
+      tags:
+        - Actuator
+      summary: Actuator web endpoint 'health'
+      operationId: handle_2
+      responses:
+        '200':
+          description: OK
+          content:
+            '*/*':
+              schema:
+                type: object
+  /actuator/health/**:
+    get:
+      tags:
+        - Actuator
+      summary: Actuator web endpoint 'health-path'
+      operationId: handle_3
+      responses:
+        '200':
+          description: OK
+          content:
+            '*/*':
+              schema:
+                type: object
+components:
+  schemas:
+    VersionsResponse:
+      properties:
+        versions:
+          type: array
+          items:
+            type: string
+    ValidationErrorResponse:
+      type: object
+      properties:
+        message:
+          type: string
+    ValidationResult:
+      type: object
+      properties:
+        renderErrors:
+          type: array
+          items:
+            type: string
+        lintWarning:
+          type: array
+          items:
+            type: string
+        lintError:
+          type: array
+          items:
+            type: string
+        versionUsed:
+          type: string
+        valid:
+          type: boolean
+        deployable:
+          type: boolean
+    Link:
+      type: object
+      properties:
+        href:
+          type: string
+        templated:
+          type: boolean
diff --git a/README.md b/README.md
index d95c4e4..44770c5 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,8 @@ or run container with LOG_LEVEL ENV
 ```
 docker run -p 8080:8080 -e LOG_LEVEL=INFO onap/org.onap.sdc.sdc-helm-validator:latest
 ```
+##### API documentation
+Swagger UI is available on endpoint: /docs. OpenAPI.yaml in the main directory contains OpenAPI 3.0.1 definition.
 
 ## Available endpoints
 * Chart validation:
@@ -83,3 +85,7 @@ Json with the following fields:
 Following Json:
 
         [ARRAY OF STRINGS] - supported helm versions
+
+* Swagger UI [GET]
+
+  `http://localhost:[PORT]/docs 
diff --git a/pom.xml b/pom.xml
index eed6d51..2ae90bf 100644
--- a/pom.xml
+++ b/pom.xml
@@ -52,6 +52,12 @@
       <version>${apache.commons.compress.version}</version>
     </dependency>
 
+    <dependency>
+      <groupId>org.springdoc</groupId>
+      <artifactId>springdoc-openapi-ui</artifactId>
+      <version>1.5.7</version>
+    </dependency>
+
   </dependencies>
 
   <dependencyManagement>
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"));