From 5bda347bc3e8843b694c795bdc72e02d6f8b8f4f Mon Sep 17 00:00:00 2001 From: Tomasz Wrobel Date: Mon, 26 Apr 2021 11:28:57 +0200 Subject: Align swagger documentation -Add examples in request parameters -Add example responses Issue-ID: SDC-3185 Signed-off-by: Tomasz Wrobel Change-Id: Ib3896d48297c4808e252c8715b380bf6e37d8003 --- .../helmvalidator/api/ValidationController.java | 29 ++++-- .../helmvalidator/config/DocsConfiguration.java | 62 ------------ .../sdc/helmvalidator/config/LoggerConfig.java | 2 + .../config/docs/DocsConfiguration.java | 107 +++++++++++++++++++++ .../config/docs/ValidationRequestParameters.java | 78 +++++++++++++++ 5 files changed, 210 insertions(+), 68 deletions(-) delete mode 100644 src/main/java/org/onap/sdc/helmvalidator/config/DocsConfiguration.java create mode 100644 src/main/java/org/onap/sdc/helmvalidator/config/docs/DocsConfiguration.java create mode 100644 src/main/java/org/onap/sdc/helmvalidator/config/docs/ValidationRequestParameters.java (limited to 'src/main') 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 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>>().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>>().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'.
" + + "Allowed formats:
" + + "- Semantic version [X.Y.Z] e.g. 3.5.2
" + + "- 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; + } +} -- cgit 1.2.3-korg