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

6 files changed, 212 insertions, 68 deletions

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);
     }