Align swagger documentation1.2.0

-Add examples in request parameters
-Add example responses

Issue-ID: SDC-3185
Signed-off-by: Tomasz Wrobel <tomasz.wrobel@nokia.com>
Change-Id: Ib3896d48297c4808e252c8715b380bf6e37d8003

7 files changed, 270 insertions, 118 deletions

diff --git a/OpenAPI.yaml b/OpenAPI.yaml
index 686d3e6..69a6de8 100644
--- a/OpenAPI.yaml
+++ b/OpenAPI.yaml
@@ -4,70 +4,49 @@ info:
   description: Application for validating Helm charts.
   version: v0
 servers:
-  - url: 'http://localhost:8080'
+  - 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/'
+      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.
+      description: Web endpoint for Helm charts validation. Helm chart in .tgz format
+        is required.
       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
+              $ref: '#/components/schemas/ValidationRequestParameters'
+        required: true
       responses:
-        '200':
-          description: Helm chart successfully validated
+        "500":
+          description: Something went wrong during validation execution
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ValidationResult'
-        '400':
-          description: Chart cannot be validated using selected version
+                $ref: '#/components/schemas/ValidationErrorResponse'
+        "200":
+          description: Helm chart successfully validated
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ValidationErrorResponse'
-        '500':
-          description: Something went wrong during validation execution
+                $ref: '#/components/schemas/ValidationResult'
+              examples:
+                Simple Validation:
+                  $ref: '#/components/examples/simpleValidation'
+                Lint Validation:
+                  $ref: '#/components/examples/validationWithLint'
+        "400":
+          description: Chart cannot be validated using selected version
           content:
             application/json:
               schema:
@@ -80,18 +59,18 @@ paths:
       description: Web endpoint for showing supported Helm versions.
       operationId: supportedVersions
       responses:
-        '200':
-          description: Supported Helm versions successfully returned
+        "500":
+          description: Something went wrong during getting Helm versions
           content:
             '*/*':
               schema:
-                $ref: '#/components/schemas/VersionsResponse'
-        '500':
-          description: Something went wrong during getting Helm versions
+                $ref: '#/components/schemas/ValidationErrorResponse'
+        "200":
+          description: Supported Helm versions successfully returned
           content:
             '*/*':
               schema:
-                $ref: '#/components/schemas/ValidationErrorResponse'
+                $ref: '#/components/schemas/VersionsResponse'
   /actuator:
     get:
       tags:
@@ -99,7 +78,7 @@ paths:
       summary: Actuator root web endpoint
       operationId: links_0
       responses:
-        '200':
+        "200":
           description: OK
           content:
             '*/*':
@@ -116,7 +95,7 @@ paths:
       summary: Actuator web endpoint 'info'
       operationId: handle_1
       responses:
-        '200':
+        "200":
           description: OK
           content:
             '*/*':
@@ -129,7 +108,7 @@ paths:
       summary: Actuator web endpoint 'health'
       operationId: handle_2
       responses:
-        '200':
+        "200":
           description: OK
           content:
             '*/*':
@@ -142,7 +121,7 @@ paths:
       summary: Actuator web endpoint 'health-path'
       operationId: handle_3
       responses:
-        '200':
+        "200":
           description: OK
           content:
             '*/*':
@@ -156,6 +135,27 @@ components:
           type: array
           items:
             type: string
+    ValidationRequestParameters:
+      required:
+        - file
+      type: object
+      properties:
+        versionDesired:
+          type: string
+          description: "Desired Helm version which should be used to validate the\
+            \ chart. If parameter is not provided validation is processing with version\
+            \ based on chart's apiVersion. Version could be provided in 'semantic\
+            \ version' or 'major version'.<br> Allowed formats: <br>- Semantic version\
+            \ [X.Y.Z] e.g. 3.5.2 <br>- Major version [vX] e.g. v3"
+        file:
+          type: string
+          format: binary
+        isLinted:
+          type: boolean
+          description: "If true, there will be an attempt to lint chart"
+        isStrictLinted:
+          type: boolean
+          description: Strict linting marks the chart as invalid if detect any warning
     ValidationErrorResponse:
       type: object
       properties:
@@ -189,3 +189,11 @@ components:
           type: string
         templated:
           type: boolean
+  examples:
+    simpleValidation:
+      description: Example response when parameter isLinted is set to false
+      value: "{\"renderErrors\":[],\"versionUsed\":\"3.5.2\",\"deployable\":true}"
+    validationWithLint:
+      description: Example response when parameter isLinted is set to true
+      value: "{\"renderErrors\":[],\"lintWarning\":[],\"lintError\":[],\"versionUsed\"\
+        :\"3.5.2\",\"valid\":true,\"deployable\":true}"
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 b766a09..7ce2656 100644
--- a/src/main/java/org/onap/sdc/helmvalidator/api/ValidationController.java
+++ b/src/main/java/org/onap/sdc/helmvalidator/api/ValidationController.java
@@ -23,10 +23,13 @@ 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.ExampleObject;
 import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.parameters.RequestBody;
 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.config.docs.ValidationRequestParameters;
 import org.onap.sdc.helmvalidator.errorhandling.ValidationErrorResponse;
 import org.onap.sdc.helmvalidator.helm.validation.ValidationService;
 import org.onap.sdc.helmvalidator.helm.validation.model.ValidationResult;
@@ -65,7 +68,13 @@ public class ValidationController {
      */
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "Helm chart successfully validated",
-            content = @Content(schema = @Schema(implementation = ValidationResult.class))),
+            content = {
+                @Content(
+                    schema = @Schema(implementation = ValidationResult.class),
+                    examples = {
+                        @ExampleObject(ref = "#/components/examples/simpleValidation", name = "Simple Validation"),
+                        @ExampleObject(ref = "#/components/examples/validationWithLint", name = "Lint Validation")
+                    })}),
         @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",
@@ -73,17 +82,25 @@ public class ValidationController {
     })
     @Operation(
         summary = "Validate chart",
-        description = "Web endpoint for Helm charts validation.",
-        tags = "ValidationService")
+        description = "Web endpoint for Helm charts validation. Helm chart in .tgz format is required.",
+        tags = "ValidationService",
+        requestBody = @RequestBody(
+            required = true,
+            content = @Content(mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
+                schema = @Schema(implementation = ValidationRequestParameters.class)
+            )
+        )
+    )
     @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")
+
+        @Parameter(hidden = true)
         @RequestParam(value = "versionDesired", required = false) String version,
         @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")
+        @Parameter(hidden = true)
         @RequestParam(value = "isLinted", required = false, defaultValue = "false") boolean isLinted,
-        @Parameter(description = "Linting should be strict or not")
+        @Parameter(hidden = true)
         @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
deleted file mode 100644
index c2c572f..0000000
--- a/src/main/java/org/onap/sdc/helmvalidator/config/DocsConfiguration.java
+++ /dev/null
@@ -1,62 +0,0 @@
-/*
- * ============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() {
-        var arraySchema = new ArraySchema();
-        arraySchema.setItems(new StringSchema());
-        return arraySchema;
-    }
-}
diff --git a/src/main/java/org/onap/sdc/helmvalidator/config/LoggerConfig.java b/src/main/java/org/onap/sdc/helmvalidator/config/LoggerConfig.java
index 065e642..b8aaef7 100644
--- a/src/main/java/org/onap/sdc/helmvalidator/config/LoggerConfig.java
+++ b/src/main/java/org/onap/sdc/helmvalidator/config/LoggerConfig.java
@@ -50,7 +50,9 @@ public class LoggerConfig {
         var loggerProperties = new Properties();
         loggerProperties.setProperty("logging.level.web", level);
         loggerProperties.setProperty("logging.level.org.springframework", level);
+        loggerProperties.setProperty("logging.level.org.springdoc", level);
         loggerProperties.setProperty("logging.level.org.apache.catalina.core", level);
+        loggerProperties.setProperty("logging.level.org.apache.tomcat", level);
         loggerProperties.setProperty("logging.level.org.onap.sdc.helmvalidator", level);
         loggerProperties.setProperty("spring.mvc.log-request-details", isDebugLevel().toString());
 
diff --git a/src/main/java/org/onap/sdc/helmvalidator/config/docs/DocsConfiguration.java b/src/main/java/org/onap/sdc/helmvalidator/config/docs/DocsConfiguration.java
new file mode 100644
index 0000000..0e5ceb6
--- /dev/null
+++ b/src/main/java/org/onap/sdc/helmvalidator/config/docs/DocsConfiguration.java
@@ -0,0 +1,107 @@
+/*
+ * ============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.docs;
+
+import com.fasterxml.jackson.annotation.JsonInclude.Include;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+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.examples.Example;
+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.Collections;
+import java.util.List;
+import java.util.Map;
+import org.onap.sdc.helmvalidator.helm.validation.model.LintValidationResult;
+import org.onap.sdc.helmvalidator.helm.validation.model.TemplateValidationResult;
+import org.onap.sdc.helmvalidator.helm.validation.model.ValidationResult;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+@OpenAPIDefinition
+public class DocsConfiguration {
+
+    private static final String EXAMPLE_VERSION = "3.5.2";
+    private static final ValidationResult SIMPLE_VALIDATION_RESPONSE_OBJECT = new ValidationResult(
+        new TemplateValidationResult(true, Collections.emptyList()),
+        EXAMPLE_VERSION);
+    private static final ValidationResult LINT_VALIDATION_RESPONSE_OBJECT = new ValidationResult(
+        new TemplateValidationResult(true, Collections.emptyList()),
+        new LintValidationResult(true, Collections.emptyList(), Collections.emptyList()),
+        EXAMPLE_VERSION);
+
+    /**
+     * Create Open API definition.
+     *
+     * @return Custom Open API definition
+     */
+    @Bean
+    public OpenAPI customOpenApi() throws JsonProcessingException {
+        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)
+                .addExamples("simpleValidation", getSimpleExample())
+                .addExamples("validationWithLint", getLintExample())
+            );
+    }
+
+    private ArraySchema getArraySchema() {
+        var arraySchema = new ArraySchema();
+        arraySchema.setItems(new StringSchema());
+        return arraySchema;
+    }
+
+    private Example getSimpleExample() throws JsonProcessingException {
+        var simpleExample = new Example();
+        simpleExample.setValue(getJsonResponse(SIMPLE_VALIDATION_RESPONSE_OBJECT));
+        simpleExample.setDescription("Example response when parameter isLinted is set to false");
+        return simpleExample;
+    }
+
+    private Example getLintExample() throws JsonProcessingException {
+        var lintExample = new Example();
+        lintExample.setValue(getJsonResponse(LINT_VALIDATION_RESPONSE_OBJECT));
+        lintExample.setDescription("Example response when parameter isLinted is set to true");
+        return lintExample;
+    }
+
+    private String getJsonResponse(ValidationResult validationResult) throws JsonProcessingException {
+        ObjectMapper mapper = getObjectMapper();
+        return mapper.writeValueAsString(validationResult);
+    }
+
+    private ObjectMapper getObjectMapper() {
+        ObjectMapper mapper = new ObjectMapper();
+        mapper.setSerializationInclusion(Include.NON_NULL);
+        return mapper;
+    }
+}
diff --git a/src/main/java/org/onap/sdc/helmvalidator/config/docs/ValidationRequestParameters.java b/src/main/java/org/onap/sdc/helmvalidator/config/docs/ValidationRequestParameters.java
new file mode 100644
index 0000000..8c8e038
--- /dev/null
+++ b/src/main/java/org/onap/sdc/helmvalidator/config/docs/ValidationRequestParameters.java
@@ -0,0 +1,78 @@
+/*
+ * ============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.docs;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.springframework.web.multipart.MultipartFile;
+
+@Schema
+public class ValidationRequestParameters {
+
+    @Schema(description = "Desired Helm version which should be used to validate the chart. "
+        + "If parameter is not provided validation is processing with version based on chart's apiVersion."
+        + " Version could be provided in 'semantic version' or 'major version'.<br> "
+        + "Allowed formats: <br>"
+        + "- Semantic version [X.Y.Z] e.g. 3.5.2 <br>"
+        + "- Major version [vX] e.g. v3")
+    private String versionDesired;
+
+    @Schema(description = "Helm chart that should be validated (packed in .tgz format)", required = true)
+    private MultipartFile file;
+
+    @Schema(description = "If true, there will be an attempt to lint chart")
+    private Boolean isLinted;
+
+    @Schema(description = "Strict linting marks the chart as invalid if detect any warning")
+    private Boolean isStrictLinted;
+
+    public String getVersionDesired() {
+        return versionDesired;
+    }
+
+    public void setVersionDesired(String versionDesired) {
+        this.versionDesired = versionDesired;
+    }
+
+    public MultipartFile getFile() {
+        return file;
+    }
+
+    public void setFile(MultipartFile file) {
+        this.file = file;
+    }
+
+    public boolean getIsLinted() {
+        return isLinted;
+    }
+
+    public void setIsLinted(boolean linted) {
+        isLinted = linted;
+    }
+
+    public boolean getIsStrictLinted() {
+        return isStrictLinted;
+    }
+
+    public void setIsStrictLinted(boolean strictLinted) {
+        isStrictLinted = strictLinted;
+    }
+}
diff --git a/src/test/java/org/onap/sdc/helmvalidator/config/LoggerConfigTest.java b/src/test/java/org/onap/sdc/helmvalidator/config/LoggerConfigTest.java
index b2ae9e5..19dda3a 100644
--- a/src/test/java/org/onap/sdc/helmvalidator/config/LoggerConfigTest.java
+++ b/src/test/java/org/onap/sdc/helmvalidator/config/LoggerConfigTest.java
@@ -81,7 +81,9 @@ class LoggerConfigTest {
     private void assertThatAllLogPropertiesHasExpectedValue(Properties properties, String expectedValue) {
         assertThat(properties.getProperty("logging.level.web")).isEqualTo(expectedValue);
         assertThat(properties.getProperty("logging.level.org.springframework")).isEqualTo(expectedValue);
+        assertThat(properties.getProperty("logging.level.org.springdoc")).isEqualTo(expectedValue);
         assertThat(properties.getProperty("logging.level.org.apache.catalina.core")).isEqualTo(expectedValue);
+        assertThat(properties.getProperty("logging.level.org.apache.tomcat")).isEqualTo(expectedValue);
         assertThat(properties.getProperty("logging.level.org.onap.sdc.helmvalidator")).isEqualTo(expectedValue);
     }